🚀 A new era: Kirby 4 Get to know
Skip to content

Collections

It often happens that we need the same set of pages or files in multiple places across our site. Think of blog articles on the blog and on the home page for example. Collections help with not repeating ourselves in such cases and to access commonly used pages or files collections more easily.

Screencast

Collections

Create custom collections of pages (projects, products, blog articles, etc.) and reuse them across your site without repeating yourself.

Define a collection

A list of pages

/site/collections/articles.php
<?php

return function ($site) {
    return $site->find('blog')->children()->listed()->flip();
};

Pages reference ›

A list of users

/site/collections/admins.php
<?php

return function ($users) {
    return $users->filterBy('role', 'admin');
};

Users reference ›

A list of images/files

/site/collections/project-covers.php
<?php

return function ($site) {
    return $site
        ->find('projects')
        ->children()
        ->images()
        ->template('cover');
};

Files reference ›

How to use collections

Collections can be used in templates and snippets like this:

$kirby->collection("articles");
$kirby->collection("admins");
$kirby->collection("project-covers");

You can loop through the collections like through any collection like this:

<?php
foreach($kirby->collection('articles') as $article) {
    echo $article->title()->html();
}
?>

Or store the collection in a variable for further use:

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

Nested collections

If you have a lot of collections, it might come handy to organize them in subfolders. Kirby can handle this:

/site/collections/articles/latest.php
<?php

return function ($site) {
    return $site->find('blog')->children()->listed()->flip();
};
$kirby->collection("articles/latest");

Best practices

  • It's always a good idea to provide a collection that is not too specific yet.
  • In general, it's better not to apply pagination to collections for example, or to set a limit. You might want to use the same set of pages in different places, but in one template you need three and in the next you need 10.