Récupérer les Données et les Ensembles de Résultats¶

Déboguer les Queries et les ResultSets¶

Étant donné que l’ORM retourne maintenant des Collections et des Entities, déboguer ces objets peut être plus compliqué qu’avec les versions précédentes de CakePHP. Il y a désormais plusieurs façons d’inspecter les données retournées par l’ORM.

• debug($query) Montre le SQL et les paramètres liés, ne montre pas les résultats.

• debug($query->all()) Montre les propriétés de ResultSet (pas les résultats).

• debug($query->toList()) Montre les résultats dans un tableau.

• debug(iterator_to_array($query)) Montre les résultats de la requête formatés en tableau.

• debug($query->toArray()) Une façon facile de montrer chacun des résultats.

• debug(json_encode($query, JSON_PRETTY_PRINT)) Résultats plus lisibles.

• debug($query->first()) Montre les propriétés d’une seule entity.

• debug((string)$query->first()) Montre les propriétés d’une seule entity en JSON.

Récupérer une Entity Unique avec une Clé Primaire¶

Cake\ORM\Table::get($id, $options = [])¶

Quand vous modifiez ou visualisez des entities et leurs données liées, il est souvent pratique de charger une entity unique à partir de la base de données. Vous pouvez faire ceci en utilisant get():

// Dans un controller ou dans une méthode de table.

// Récupère un article unique
$article = $articles->get($id);

// Récupère un article unique, et les commentaires liés
$article = $articles->get($id, [
    'contain' => ['Comments']
]);

Si l’opération get ne trouve aucun résultat, une Cake\Datasource\Exception\RecordNotFoundException sera levée. Vous pouvez soit attraper cette exception vous-même, soit permettre à CakePHP de la convertir en une erreur 404.

Comme find(), get() a un cache intégré. Vous pouvez utiliser l’option cache quand vous appelez get() pour appliquer la mise en cache:

// Dans un controller ou dans une méthode de table.

// Utiliser une configuration de cache quelconque,
// ou une instance de CacheEngine & une clé générée
$article = $articles->get($id, [
    'cache' => 'cache_personnalise',
]);

// Utilise une configuration de cache quelconque,
// ou une instance de CacheEngine & une clé spécifique
$article = $articles->get($id, [
    'cache' => 'cache_personnalise', 'key' => 'ma_cle'
]);

// Désactive explicitement la mise en cache
$article = $articles->get($id, [
    'cache' => false
]);

Une autre possibilité est de faire un get() d’une entity en utilisant Méthodes Finder Personnalisées. Par exemple si vous souhaitez récupérer toutes les traductions pour une entity, vous pouvez le faire en utilisant l’option finder:

$article = $articles->get($id, [
    'finder' => 'traductions',
]);

Utiliser les Finders pour Charger les Données¶

Cake\ORM\Table::find($type, $options = [])¶

Avant de travailler avec les entities, vous devrez les charger. La façon la plus facile de le faire est d’utiliser la méthode find. La méthode find est un moyen simple et extensible pour trouver les données qui vous intéressent:

// Dans un controller ou dans une méthode de table.

// Trouver tous les articles
$query = $articles->find('all');

La valeur retournée par une méthode find est toujours un objet Cake\ORM\Query. La classe Query vous permet de réaffiner une requête après l’avoir créée. Les objets Query sont évalués lazily, et ne s’exécutent qu’à partir du moment où vous commencez à récupérer des lignes, les convertissez en tableau, ou quand la méthode all() est appelée:

// Dans un controller ou dans une méthode de table.

// Trouver tous les articles.
// À ce niveau, la requête n'est pas lancée.
$query = $articles->find('all');

// L'itération va exécuter la requête.
foreach ($query->all() as $row) {
}

// Appeler all() va exécuter la requête
// et retourner l'ensemble des résultats.
$results = $query->all();

// Une fois le résultat obtenu, nous pouvons en récupérer toutes les lignes
$data = $results->toList();

// Convertir la requête en tableau associatif va l'exécuter.
$data = $query->toArray();

// Dans un controller ou dans une méthode de table.
$query = $articles->find('all')
    ->where(['Articles.created >' => new DateTime('-10 days')])
    ->contain(['Comments', 'Authors'])
    ->limit(10);

Vous pouvez aussi fournir à find() plusieurs options couramment utilisées. Cela peut être utile pour les tests puisqu’il y a peu de méthodes à mocker:

// Dans un controller ou dans une méthode de table
$query = $articles->find('all', [
    'conditions' => ['Articles.created >' => new DateTime('-10 days')],
    'contain' => ['Authors', 'Comments'],
    'limit' => 10
]);

La liste des options supportées par find() est :

• conditions fournit des conditions pour la clause WHERE de la requête.

• limit définit le nombre de lignes que vous voulez.

• offset définit l’offset de la page que vous souhaitez. Vous pouvez aussi utiliser page pour faciliter le calcul.

• contain définit les associations à charger en eager.

• fields limite les champs chargés dans l’entity. Le fait de ne pas charger tous les champs peut cependant faire que les entities se comportent de manière inappropriée.

• group ajoute une clause GROUP BY à votre requête. C’est utile quand vous utilisez des fonctions d’agrégation.

• having ajoute une clause HAVING à votre requête.

• join définit les jointures personnalisées supplémentaires.

• order trie l’ensemble des résultats.

Les options qui ne sont pas dans cette liste seront passées aux écouteurs de beforeFind, où ils pourront être utilisés pour modifier l’objet requête. Vous pouvez utiliser la méthode getOptions sur un objet query pour récupérer les options utilisées. Bien que vous puissiez passer des objets requête à vos controllers, nous vous recommandons plutôt de les rassembler dans des Méthodes Finder Personnalisées. En utilisant des méthodes finder personnalisées, vous pourrez réutiliser vos requêtes et cela facilitera les tests.

Par défaut, les requêtes et les result sets renverront des objets Entities. Vous pouvez récupérer des tableaux basiques en désactivant l’hydratation:

$query->disableHydration();

// $data est le ResultSet qui contient le tableau de données.
$data = $query->all();

Récupérer les Premiers Résultats¶

La méthode first() vous permet de récupérer seulement la première ligne d’une requête. Si la requête n’a pas été exécutée, une clause LIMIT 1 sera appliquée:

// Dans un controller ou dans une méthode de table.
$query = $articles->find('all', [
    'order' => ['Articles.created' => 'DESC']
]);
$row = $query->first();

Cette approche remplace le find('first') des versions précédentes de CakePHP. Vous pouvez aussi utiliser la méthode get() si vous recherchez les entities par leur clé primaire.

Récupérer un Nombre de Résultats¶

Une fois que vous avez créé un objet query, vous pouvez utiliser la méthode count() pour récupérer un décompte des résultats de cette query:

// Dans un controller ou une méthode de table.
$query = $articles->find('all', [
    'conditions' => ['Articles.title LIKE' => '%Ovens%']
]);
$number = $query->count();

Consultez Retourner le Nombre Total d’Enregistrements pour d’autres utilisations de la méthode count().

Trouver les Paires de Clé/Valeur¶

Cette fonctionnalité est pratique pour générer un tableau associatif de données à partir des données de votre application. C’est notamment très utile pour la création des elements <select>. CakePHP fournit une méthode simple à utiliser pour générer des listes de données:

// Dans un controller ou dans une méthode de table.
$query = $articles->find('list');
$data = $query->toArray();

// Les données ressemblent maintenant à ceci
$data = [
    1 => 'Premier post',
    2 => 'Mon deuxième article',
];

Sans autre option, les clés de $data correspondront à la clé primaire de votre table, tandis que les valeurs seront celles du champ désigné dans le paramètre “displayField” de la table. Le “displayField” par défaut est title ou name. Vous pouvez utiliser la méthode setDisplayField() de la table pour configurer le champ à afficher:

class ArticlesTable extends Table
{

    public function initialize(array $config): void
    {
        $this->setDisplayField('label');
    }
}

Au moment où vous appelez list, vous pouvez configurer les champs utilisés comme clé et comme valeur respectivement avec les options keyField et valueField:

// Dans un controller ou dans une méthode de table.
$query = $articles->find('list', [
    'keyField' => 'slug',
    'valueField' => 'label'
]);
$data = $query->toArray();

// Les données ressemblent maintenant à
$data = [
    'premier-post' => 'Premier post',
    'mon-deuxieme-article' => 'Mon deuxième article',
];

Les résultats peuvent être regroupés. C’est utile quand vous voulez organiser valeurs en sous-groupes, ou que vous voulez construire des elements <optgroup> avec FormHelper:

// Dans un controller ou dans une méthode de table.
$query = $articles->find('list', [
    'keyField' => 'slug',
    'valueField' => 'label',
    'groupField' => 'author_id'
]);
$data = $query->toArray();

// Les données ressemblent maintenant à
$data = [
    1 => [
        'premier-post' => 'Premier post',
        'mon-deuxieme-article' => 'Mon deuxième article',
    ],
    2 => [
        // Les articles d'autres auteurs.
    ]
];

Vous pouvez aussi créer une liste de données à partir d’associations pouvant être réalisées avec une jointure:

$query = $articles->find('list', [
    'keyField' => 'id',
    'valueField' => 'author.name'
])->contain(['Authors']);

Les expressions keyField, valueField, et groupField font référence au chemin des attributs dans les entités, et non sur des colonnes de la base de données. Vous pouvez donc utiliser des champs virtuels dans les résultats de find(list).

// Dans votre Entity Authors, créez un champ virtuel
// à utiliser en tant que champ à afficher:
protected function _getLibelle()
{
    return $this->_fields['first_name'] . ' ' . $this->_fields['last_name']
      . ' / ' . __('User ID %s', $this->_fields['user_id']);
}

// Dans vos finders/controller:
$query = $articles->find('list', [
        'keyField' => 'id',
        'valueField' => function ($article) {
            return $article->author->get('label');
        }
    ])
    ->contain('Authors');

// Dans AuthorsTable::initialize():
$this->setDisplayField('label'); // Va utiliser Author::_getLabel()
// Dans vos finders/controller:
$query = $authors->find('list'); // Va utiliser AuthorsTable::getDisplayField()

Trouver des Données Filées¶

Le finder find('threaded') retourne des entities imbriquées qui sont filées ensemble grâce à un champ servant de clé. Par défaut, ce champ est parent_id. Ce finder vous permet d’accéder aux données stockées dans une table de style “liste adjacente”. Toutes les entities qui correspondent à un parent_id donné sont placées sous l’attribut children:

// Dans un controller ou dans une méthode table.
$query = $comments->find('threaded');

// Expanded les valeurs par défaut
$query = $comments->find('threaded', [
    'keyField' => $comments->primaryKey(),
    'parentField' => 'parent_id'
]);
$results = $query->toArray();

echo count($results[0]->children);
echo $results[0]->children[0]->comment;

Les clés parentField et keyField peuvent être utilisées pour définir les champs qui vont servir au filage.

Méthodes Finder Personnalisées¶

Les exemples ci-dessus montrent comment utiliser les finders intégrés all et list. Cependant, il est possible et recommandé d’implémenter vos propres méthodes finder. Les méthodes finder sont idéales pour rassembler des requêtes utilisées couramment, ce qui vous permet de fournir une abstraction facile à utiliser pour de nombreux détails de la requête. Les méthodes finder sont définies en créant des méthodes nomméed par convention findFoo, où Foo est le nom que vous souhaitez donner à votre finder. Par exemple, si nous voulons ajouter à notre table d’articles un finder servant à rechercher parmi les articles d’un certain auteur, nous ferions ceci:

use Cake\ORM\Query;
use Cake\ORM\Table;

class ArticlesTable extends Table
{

    public function findEcritPar(Query $query, array $options)
    {
        $user = $options['user'];
        return $query->where(['author_id' => $user->id]);
    }

}

$query = $articles->find('ecritPar', ['user' => $userEntity]);

Les méthodes finder peuvent modifier la requête comme il se doit, ou utiliser l’argument $options pour personnaliser l’opération finder selon la logique souhaitée. Vous pouvez aussi “empiler” les finders, ce qui permet d’exprimer sans effort des requêtes complexes. En supposant que vous ayez à la fois des finders “published” et “recent”, vous pourriez très bien faire ceci:

$query = $articles->find('published')->find('recent');

Bien que tous les exemples que nous avons cités jusqu’ici montrent des finders qui s’appliquent sur des tables, il est aussi possible de définir des méthodes finder sur des Behaviors (Comportements).

Si vous devez modifier les résultats après qu’ils ont été récupérés, vous pouvez utiliser une fonction Modifier les Résultats avec Map/Reduce. Les fonctionnalités de map reduce remplacent le callback “afterFind” présent dans les précédentes versions de CakePHP.

Finders Dynamiques¶

L’ORM de CakePHP fournit des finders construits dynamiquement, qui vous permettent d’exprimer des requêtes simples sans écrire de code particulier. Par exemple, admettons que vous recherchiez un utilisateur à partir de son username. Vous pourriez procéder ainsi:

// Dans un controller
// Les deux appels suivants sont équivalents.
$query = $this->Users->findByUsername('joebob');
$query = $this->Users->findAllByUsername('joebob');

Les finders dynamiques permettent même de filtrer sur plusieurs champs à la fois:

$query = $users->findAllByUsernameAndApproved('joebob', 1);

Vous pouvez aussi créer des conditions OR:

$query = $users->findAllByUsernameOrEmail('joebob', '[email protected]');

Vous pouvez utiliser des conditions OR ou AND, mais vous ne pouvez pas combiner les deux dans un même finder dynamique. Les autres options de requête comme contain ne sont pas non plus supportées par les finders dynamiques. Vous devrez utiliser des Méthodes Finder Personnalisées pour encapsuler des requêtes plus complexes. Pour finir, vous pouvez aussi combiner les finders dynamiques avec des finders personnalisés:

$query = $users->findTrollsByUsername('bro');

Ce qui se traduirait ainsi:

$users->find('trolls', [
    'conditions' => ['username' => 'bro']
]);

Une fois que vous avez un objet query créé à partir d’un finder dynamique, vous devrez appeler first() si vous souhaitez récupérer le premier résultat.

Récupérer les Données Associées¶

Pour récupérer des données associées, ou filtrer selon les données associées, il y a deux façons de procéder:

• utiliser des fonctions de requêtage de l’ORM de CakePHP telles que contain() et matching()

• utiliser des fonctions de jointures telles que innerJoin(), leftJoin(), et rightJoin().

Vous devriez utiliser contain() quand vous voulez charger le modèle primaire et ses données associées. Bien que contain() vous permette d’appliquer des conditions supplémentaires sur les associations chargées, vous ne pouvez pas filtrer le modèle primaire en fonction des données associées. Pour plus de détails sur contain(), consultez Eager Loading des Associations Via Contain.

Vous devriez utiliser matching() quand vous souhaitez filtrer le modèle primaire en fonction des données associées. Par exemple, quand vous voulez charger tous les articles auxquels est associé un tag spécifique. Pour plus de détails sur matching(), consultez Filtrer par les Données Associées Via Matching et Joins.

Si vous préférez utiliser les fonctions de jointure, vous pouvez consulter Ajouter des Jointures pour plus d’informations.

Eager Loading des Associations Via Contain¶

Par défaut, CakePHP ne charge aucune donnée associée lors de l’utilisation de find(). Vous devez faire un “contain” ou charger en eager chaque association que vous souhaitez voir figurer dans vos résultats.

L’eager loading aide à éviter la plupart des problèmes potentiels de performance qui entourent le lazy loading dans un ORM. Les requêtes générées par eager loading peuvent davantage tirer parti des jointures, ce qui permet de créer des requêtes plus efficaces. Dans CakePHP, vous utilisez la méthode “contain” pour indiquer quelles associations doivent être chargées en eager:

// Dans un controller ou une méthode de table.

// En option du find()
$query = $articles->find('all', ['contain' => ['Authors', 'Comments']]);

// En méthode sur un objet query
$query = $articles->find('all');
$query->contain(['Authors', 'Comments']);

Ceci va charger les auteurs et commentaires liés à chaque article du result set. Vous pouvez charger des associations imbriquées en utilisant les tableaux imbriqués pour définir les associations à charger:

$query = $articles->find()->contain([
    'Authors' => ['Addresses'], 'Comments' => ['Authors']
]);

Au choix, vous pouvez aussi exprimer des associations imbriquées en utilisant la notation par points:

$query = $articles->find()->contain([
    'Authors.Addresses',
    'Comments.Authors'
]);

Vous pouvez charger les associations en eager aussi profondément que vous le souhaitez:

$query = $produits->find()->contain([
    'Shops.Cities.Countries',
    'Shops.Managers'
]);

Vous pouvez sélectionner des champs de toutes les associations en utilisant plusieurs appels à contain():

$query = $this->find()->select([
    'Realestates.id',
    'Realestates.title',
    'Realestates.description'
])
->contain([
    'RealestatesAttributes' => [
        'Attributes' => [
            'fields' => [
                // Les champs dépendant d'un alias doivent inclure le préfixe
                // du modèle dans contain() pour être mappés correctement.
                'Attributes__name' => 'attr_name'
            ]
        ]
    ]
])
->contain([
    'RealestatesAttributes' => [
        'fields' => [
            'RealestatesAttributes.realestate_id',
            'RealestatesAttributes.value'
        ]
    ]
])
->where($condition);

Si vous avez besoin de réinitialiser les contain sur une requête, vous pouvez définir le second argument à true:

$query = $articles->find();
$query->contain(['Authors', 'Comments'], true);

// Dans un controller ou une méthode de table.
$query = $articles->find()->contain('Comments', function (Query $q) {
    return $q
        ->select(['contenu', 'author_id'])
        ->where(['Comments.approved' => true]);
});

$this->paginate['contain'] = [
    'Comments' => function (Query $query) {
        return $query->select(['body', 'author_id'])
        ->where(['Comments.approved' => true]);
    }
];

$query = $articles->find()->contain([
    'Comments',
    'Authors.Profiles' => function (Query $q) {
        return $q->where(['Profiles.is_published' => true]);
    }
]);

// Récupère tous les articles, mais récupère seulement les commentaires qui
// sont approuvés et populaires.
$query = $articles->find()->contain('Comments', function ($q) {
    return $q->find('approved')->find('popular');
});

$query = $articles->find()->contain([
    'Authors' => [
        'foreignKey' => false,
        'queryBuilder' => function (Query $q) {
            return $q->where(...); // Conditions complètes pour le filtrage
        }
    ]
]);

// Sélectionne id & title de articles, mais aussi tous les champs de Users.
$query = $articles->find()
    ->select(['id', 'title'])
    ->select($articles->Users)
    ->contain(['Users']);

// Sélectionne id & title de articles, mais tous les champs de
// Users, Comments et Tags.
$query->select(['id', 'title'])
    ->contain(['Comments', 'Tags'])
    ->enableAutoFields(true)
    ->contain(['Users' => function(Query $q) {
        return $q->autoFields(true);
    }]);

$query->contain([
    'Comments' => [
        'sort' => ['Comments.created' => 'DESC']
    ]
]);

Filtrer par les Données Associées Via Matching et Joins¶

Un cas de requête couramment utilisé avec les associations consiste à trouver les enregistrements qui correspondent à certaines données associées. Par exemple si vous avez une association “Articles belongsToMany Tags”, vous voudrez probablement trouver les Articles qui portent le tag CakePHP. C’est extrêmement simple à faire avec l’ORM de CakePHP:

// Dans un controller ou une méthode de table.

$query = $articles->find();
$query->matching('Tags', function ($q) {
    return $q->where(['Tags.name' => 'CakePHP']);
});

Vous pouvez aussi appliquer cette stratégie aux associations HasMany. Par exemple si “Authors HasMany Articles”, vous pouvez trouver tous les auteurs ayant publié un article récemment en écrivant ceci:

$query = $authors->find();
$query->matching('Articles', function ($q) {
    return $q->where(['Articles.created >=' => new DateTime('-10 days')]);
});

La syntaxe de contain(), qui doit déjà vous être familière, permet aussi de filtrer des associations imbriquées:

// Dans un controller ou une méthode de table.
$query = $produits->find()->matching(
    'Shops.Cities.Countries', function ($q) {
        return $q->where(['Countries.name' => 'Japon']);
    }
);

// Récupère les articles qui ont été commentés par 'markstory',
// en passant une variable.
// Utiliser la notation par points plutôt que des appels imbriqués à matching()
$username = 'markstory';
$query = $articles->find()->matching('Comments.Users', function ($q) use ($username) {
    return $q->where(['username' => $username]);
});

Les données des associations qui correspondent aux conditions (données matchées) seront disponibles dans l’attribut _matchingData des entities. Si vous utilisez à la fois match et contain sur la même association, vous pouvez vous attendre à avoir à la fois la propriété _matchingData et la propriété standard d’association dans vos résultats.

$query = $articles->find();
$query->innerJoinWith('Tags', function ($q) {
    return $q->where(['Tags.name' => 'CakePHP']);
});

$query = $products->find()->innerJoinWith(
    'Shops.Cities.Countries', function ($q) {
        return $q->where(['Countries.name' => 'Japon']);
    }
);

$filter = ['Tags.name' => 'CakePHP'];
$query = $articles->find()
    ->distinct($articles->getPrimaryKey())
    ->contain('Tags', function (Query $q) use ($filter) {
        return $q->where($filter);
    })
    ->innerJoinWith('Tags', function (Query $q) use ($filter) {
        return $q->where($filter);
    });

$query
    ->select(['country_name' => 'Countries.name'])
    ->innerJoinWith('Countries');

// Dans un controller ou une méthode de table.

$query = $articlesTable
    ->find()
    ->notMatching('Tags', function ($q) {
        return $q->where(['Tags.name' => 'ennuyeux']);
    });

$query = $authorsTable
    ->find()
    ->notMatching('Articles', function ($q) {
        return $q->where(['Articles.created >=' => new \DateTime('-10 days')]);
    });

$query = $articlesTable
    ->find()
    ->notMatching('Comments.Users', function ($q) {
        return $q->where(['username' => 'jose']);
    });

$query = $articlesTable
    ->find()
    ->notMatching('Comments.Users', function ($q) {
        return $q->where(['username' => 'jose']);
    })
    ->matching('Comments');

$query = $articlesTable->find();
$query->select(['total_comments' => $query->func()->count('Comments.id')])
    ->leftJoinWith('Comments')
    ->group(['Articles.id'])
    ->enableAutoFields(true);

$query = $authorsTable
    ->find()
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles.Tags', function ($q) {
        return $q->where(['Tags.name' => 'redoutable']);
    })
    ->group(['Authors.id'])
    ->enableAutoFields(true);

Changer les Stratégies de Récupération¶

Comme cela a été dit, vous pouvez personnaliser la stratégie (strategy) utilisée par une association dans un contain().

Si vous observez les options des associations BelongsTo et HasOne, vous constaterez que la stratégie par défaut “join” et le type de jointure (joinType) “INNER” peuvent être remplacés par “select”:

$query = $articles->find()->contain([
    'Comments' => [
        'strategy' => 'select',
    ]
]);

Cela peut être utile lorsque vous avez besoin de conditions qui ne font pas bon ménage avec une jointure. Cela ouvre aussi la possibilité de requêter des tables entre lesquelles vous n’avez pas l’autorisation de faire des jointures, par exemple des tables se trouvant dans deux bases de données différentes.

Habituellement, vous définisser la stratégie d’une association quand vous la définissez, dans la méthode Table::initialize(), mais vous pouvez changer manuellement la stratégie de façon permanente:

$articles->Comments->setStrategy('select');

$query = $articles->find()->contain([
    'Comments' => [
            'strategy' => 'subquery',
            'queryBuilder' => function ($q) {
                return $q->where(['Comments.approved' => true]);
            }
    ]
]);

Lazy loading des Associations¶

CakePHP propose le chargement de vos associations en eager. Cependant il y a des cas où vous aurez besoin de charger les associations en lazy. Consultez les sections Lazy Loading des Associations et Charger des Associations Supplémentaires pour plus d’informations.

Travailler sur les Résultats (Result Sets)¶

Une fois qu’une requête est exécutée avec all(), vous récupérez une instance de Cake\ORM\ResultSet. Cet objet propose des outils puissants pour manipuler les données renvoyées par vos requêtes. Comme les objets Query, un ResultSet est une Collection et vous pouvez donc appeler sur celui-ci n’importe quelle méthode propre aux collections.

Les objets ResultSet vont charger les lignes paresseusement (lazily) à partir de la requête préparée sous-jacente. Par défaut, les résultats seront mis en mémoire tampon, vous permettant ainsi de parcourir les résultats plusieurs fois, ou de mettre les résultats en cache et d’itérer dessus. Si vous travaillez sur un ensemble de données trop large pour tenir en mémoire, vous pouvez désactiver la mise en mémoire tampon depuis la requête pour travailler sur les résultats à la volée:

$query->disableBufferedResults();

Stopper la mise en mémoire tampon appelle quelques mises en garde:

1. Vous ne pourrez itérer les résultats qu’une seule fois.

2. Vous ne pourrez pas non plus itérer et mettre en cache les résultats.

3. La mise en mémoire tampon ne peut pas être désactivée pour les requêtes qui chargent en eager les associations hasMany ou belongsToMany, puisque ces types d’association nécessitent le chargement en eager de tous les résultats afin de générer les requêtes dépendantes.

Les ResultSets vous permettent de mettre en cache, de sérialiser ou d’encoder en JSON les résultats:

// Dans un controller ou une méthode de table.
$results = $query->all();

// Serialisé
$serialized = serialize($results);

// Json
$json = json_encode($results);

La sérialisation des ResultSets et l’encodage en JSON fonctionnent comme vous pouvez vous y attendre. Les données sérialisées peuvent être désérialisées en un ResultSet fonctionnel. La conversion en JSON respecte la configuration des champs cachés et des champs virtuels dans tous les objets entity inclus dans le ResultSet.

Les ResultSets sont des objets “Collection” et supportent les mêmes méthodes que les objets collection. Par exemple, vous pouvez extraire une liste des tags uniques sur une collection d’articles en exécutant:

// Dans un controller ou une méthode de table.
$query = $articles->find()->contain(['Tags']);

$reducer = function ($output, $value) {
    if (!in_array($value, $output)) {
        $output[] = $value;
    }
    return $output;
};

$uniqueTags = $query->all()
    ->extract('tags.name')
    ->reduce($reducer, []);

Ci-dessous quelques autres exemples de méthodes de collection utilisées avec des ResultSets:

// Filtre les lignes sur une propriété calculée
$filtered = $results->filter(function ($row) {
    return $row->is_recent;
});

// Crée un tableau associatif depuis les propriétés du résultat
$results = $articles->find()->contain(['Authors'])->all();

$authorsList = $results->combine('id', 'author.name');

Le chapitre Collections comporte plus de détails sur ce qu’on peut faire avec les fonctionnalités des collections sur des ResultSets. La section Ajouter des Champs Calculés montre comment ajouter des champs calculés, ou remplacer le ResutSet.

$result = $articles->find('all')->all();

// Récupère le premier et/ou le dernier résultat.
$row = $result->first();
$row = $result->last();

$result = $articles->find('all')->all();

// Récupère le 5ème enregistrement
$row = $result->skip(4)->first();

// Vérifie une requête.
$query->isEmpty();

// Vérifie les résultats.
$results = $query->all();
$results->isEmpty();

$articles = $this->Articles->find()->all();
$withMore = $this->Articles->loadInto($articles, ['Comments', 'Users']);

Modifier les Résultats avec Map/Reduce¶

La plupart du temps, les opérations find nécessitent un traitement après-coup des données de la base de données. Les accesseurs (getters) des entities peuvent s’occuper de générer la plupart des propriétés virtuelles ou des formats de données particuliers ; néanmoins vous serez parfois amené à changer la structure des données de façon plus radicale.

Pour ces situations, l’objet Query propose la méthode mapReduce(), qui est une façon de traiter les résultats après qu’ils ont été récupérés dans la base de données.

Un exemple classique de changement de structure de données est le regroupement des résultats selon certaines conditions. Nous pouvons utiliser la fonction mapReduce() pour cette tâche. Nous avons besoin de deux fonctions appelées $mapper et $reducer. La fonction $mapper reçoit en premier argument un résultat de la base de données, en second argument la clé d’itération et en troisième elle reçoit une instance de la routine MapReduce en train d’être éxecutée:

$mapper = function ($article, $key, $mapReduce) {
    $status = 'published';
    if ($article->isDraft() || $article->isInReview()) {
        $status = 'unpublished';
    }
    $mapReduce->emitIntermediate($article, $status);
};

Dans cet exemple, $mapper calcule le statut d’un article, soit publié soit non publié. Ensuite il appelle emitIntermediate() sur l’instance MapReduce. Cette méthode insère l’article dans la liste des articles soit sous l’étiquette “publié”, soit sous l’étiquette “non publié”.

La prochaine étape dans le processus de map-reduce est la consolidation des résultats finaux. La fonction $reducer sera appelée sur chaque statut créé dans le mapper, de manière à ce que vous puissiez faire des traitements supplémentaires. Cette fonction va recevoir la liste des articles d’un certain « tas » en premier paramètre, le nom du tas à traiter en second paramètre, et à nouveau, comme pour la fonction mapper(), l’instance de la routine MapReduce en troisième paramètre. Dans notre exemple, nous n’avons pas besoin de retraiter les listes d’articles une fois qu’elles sont constituées, donc nous nous contentons d’émettre (emit) les résultats finaux:

$reducer = function ($articles, $status, $mapReduce) {
    $mapReduce->emit($articles, $status);
};

Pour finir, nous pouvons passer ces deux fonctions pour exécuter le regroupement:

$articlesByStatus = $articles->find()
    ->where(['author_id' => 1])
    ->mapReduce($mapper, $reducer)
    ->all();

foreach ($articlesByStatus as $status => $articles) {
    echo sprintf("Il y a %d articles avec le statut %s", count($articles), $status);
}

Ce qui va afficher la sortie suivante:

Il y a 4 articles avec le statut published
Il y a 5 articles avec le statut unpublished

Bien sûr, ceci est un exemple simple qui pourrait être résolu d’une autre façon sans l’aide d’un traitement map-reduce. Maintenant, regardons un autre exemple dans lequel la fonction reducer sera nécessaire pour faire quelque chose de plus que d’émettre les résultats.

Pour calculer les mots mentionnés le plus souvent dans les articles contenant des informations sur CakePHP, comme d’habitude nous avons besoin d’une fonction mapper:

$mapper = function ($article, $key, $mapReduce) {
    if (stripos($article['body'], 'cakephp') === false) {
        return;
    }

    $words = array_map('strtolower', explode(' ', $article['body']));
    foreach ($words as $word) {
        $mapReduce->emitIntermediate($article['id'], $word);
    }
};

Elle vérifie d’abord si le mot « cakephp » est dans le corps de l’article, et ensuite coupe le corps en mots individuels. Chaque mot va créer son propre tas, où chaque id d’article sera stocké. Maintenant réduisons nos résultats pour extraire seulement le décompte du nombre de mots:

$reducer = function ($occurrences, $word, $mapReduce) {
    $mapReduce->emit(count($occurrences), $word);
}

Pour finir, nous mettons tout ensemble:

$nbMots = $articles->find()
    ->where(['published' => true])
    ->andWhere(['publication_date >=' => new DateTime('2014-01-01')])
    ->disableHydration()
    ->mapReduce($mapper, $reducer)
    ->all();

Ceci pourrait retourner un tableau très grand si nous ne purgeons pas les petits mots, mais cela pourrait ressembler à ceci:

[
    'cakephp' => 100,
    'génial' => 39,
    'impressionnant' => 57,
    'remarquable' => 10,
    'hallucinant' => 83
]

Un dernier exemple et vous serez un expert de map-reduce. Imaginez que vous ayez une table amis et que vous souhaitiez trouver les « faux amis » dans notre base de données ou, autrement dit, des gens qui ne se suivent pas mutuellement. Commençons avec notre fonction mapper():

$mapper = function ($rel, $key, $mr) {
    $mr->emitIntermediate($rel['target_user_id'], $rel['source_user_id']);
    $mr->emitIntermediate(-$rel['source_user_id'], $rel['target_user_id']);
};

Le tableau intermédiaire ressemblera à ceci:

[
    1 => [2, 3, 4, 5, -3, -5],
    2 => [-1],
    3 => [-1, 1, 6],
    4 => [-1],
    5 => [-1, 1],
    6 => [-3],
    ...
]

La clé de premier niveau étant un utilisateur, les nombres positifs indiquent que l’utilisateur suit d’autres utilisateurs et les nombres négatifs qu’il est suivi par d’autres utilisateurs.

Maintenant, il est temps de la réduire. Pour chaque appel au reducer, il va recevoir une liste de followers par utilisateur:

$reducer = function ($friends, $user, $mr) {
    $fakeFriends = [];

    foreach ($friends as $friend) {
        if ($friend > 0 && !in_array(-$friend, $friends)) {
            $fakeFriends[] = $friend;
        }
    }

    if ($fakeFriends) {
        $mr->emit($fakeFriends, $user);
    }
};

Et nous fournissons nos fonctions à la requête:

$fakeFriends = $friends->find()
    ->disableHydration()
    ->mapReduce($mapper, $reducer)
    ->all();

Ceci retournerait un tableau ressemblant à:

[
    1 => [2, 4],
    3 => [6]
    ...
]

Ce tableau final signifie, par exemple, que l’utilisateur avec l’id 1 suit les utilisateurs 2 et 4, mais ceux-ci ne suivent pas 1 de leur côté.

$query = $articles->find()
    ->where(['published' => true])
    ->mapReduce($mapper, $reducer);

// Plus loin dans votre app:
$query->where(['created >=' => new DateTime('1 day ago')]);

public function findPublished(Query $query, array $options)
{
    return $query->where(['published' => true]);
}

public function findRecent(Query $query, array $options)
{
    return $query->where(['created >=' => new DateTime('1 day ago')]);
}

public function findCommonWords(Query $query, array $options)
{
    // Comme dans l'exemple précédent sur la fréquence des mots
    $mapper = ...;
    $reducer = ...;
    return $query->mapReduce($mapper, $reducer);
}

$motsCourant = $articles
    ->find('commonWords')
    ->find('published')
    ->find('recent');

$mapper = function ($count, $word, $mr) {
    if ($count > 20) {
        $mr->emit($count, $word);
    }
};

$articles->find('commonWords')->mapReduce($mapper)->all();

$query->mapReduce(null, null, true);