Qu'est ce qu'une collection ?

Une collection est un fichier PHP qui renvoie une fonction anonyme renvoyant elle-même un objet $pages, $files ou $users. Une collection peut donc contenir des pages, des fichiers ou des utilisateurs de votre application. L'intérêt de créer une collection c'est d'éviter de répéter du code à plusieurs endroits de votre site web.

Comment définir une collection ?

Pour définir une collection, il faut créer un fichier PHP et le déposer dans un dossier /site/collections/.

Vous pouvez donner le nom que vous souhaitez à ce fichier PHP et vous pouvez également créer des sous-dossiers dans le dossier /site/collections/ pour mieux organiser vos fichiers si vous êtes amené à créer plusieurs collections.

Voici quelques exemples de création de collections :

1- Créer une collection de pages

// /site/collections/posts.php

<?php

return function ($site) {
    return $site->find('notes')->children()->listed();
};
Vous noterez que pour accéder à l'objet $site dans la fonction anonyme, il suffit de le passer en paramètre. Ca sera aussi le cas si vous avez besoin de l'objet $users.

Quelques explications :

$site->find('notes') : je parts de l'objet $site et je cherche la page ayant l'ID 'notes' (mes posts sont des sous-pages de la page notes)
$site->find('notes')->children() : je récupère les enfants (sous-pages) de la page 'notes'

$site->find('notes')->children()->listed() : je ne garde que les sous-pages ayant le statut 'listed'

2- Créer une collection de fichiers

// /site/collections/photos.php

<?php

return function ($site) {
    return $site->find('album')->children()->images();
};

3- Créer une collection d'utilisateurs

// /site/collections/authors.php

<?php

return function ($users) {
    return $users->filterBy('role', 'authors');
};
Vous trouverez toutes les méthodes disponibles pour l'objet $site et $users dans la documentation de Kirby.

Comment utiliser une collection ?

Vos collections peuvent être appelées depuis vos templates, vos snippets, vos controllers, vos pages models ... de la façon suivante :

// /site/templates/home.php

<?php

$posts = $kirby->collection('posts');

foreach( $posts as $post ) {
    echo $post->title()->html();
}

Si votre collection est stockée dans un sous-dossier du dossier /site/collections/ par exemple /site/collections/blog/posts.php elle pourra être appelée comme ceci :

// /site/templates/home.php

<?php

$posts = $kirby->collection('blog/posts');

La vidéo YouTube