Collections

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that some pages, screenshots, and technical reference may still reflect older versions.

Collections (opens new window) come from the Laravel (opens new window) ecosystem, and provide a fluid way of working with array-like data.

You can create a Collection anywhere:

{% set list = collect(['Green', 'Teal', 'Blue']) %}

Collections can be used in most situations that an array would be:

<ul>
  {% for color in colors %}
    {# `color` is one of our original three strings: #}
    <li>{{ color }}</li>
  {% endfor %}
</ul>

# Methods

Dozens of convenience methods (opens new window) are available on every collection to simplify cumbersome or error-prone operations.

These methods can be chained together to process data in an elegant way. Take this average review score logic:

{% set recentReviews = craft.entries()
  .section('reviews')
  .relatedTo({
    targetElement: product,
  })
  .postDate(">= #{now|date_modify('-1 month')}")
  .collect() %}

{{ recentReviews.pluck('rating').average() }}

Not all Collection methods return another Collection! In this example, .pluck() (opens new window) does (containing just the rating field values), but .average() (opens new window) doesn’t (instead returning a float (opens new window)). As Collections are intended for working with lists, methods that return scalar values can only be used at the “end” of a chain.

Some common array-manipulation features are already implemented in Craft as Twig filters or functions, but equivalent methods are usually available via Collections. Their supported arguments and signatures may differ slightly, so consult the documentation if you are combining or switching between features.

One common problem, however, is that Twig’s default configuration does not parse anonymous functions or “closures” in every expression context. The nystudio107/craft-closure package (opens new window) provides a shim to work around this limitation.

# Element Queries

Use the .collect() query execution method (in place of .all()) to return elements as a Collection. You can also wrap an existing list of elements in a Collection with the same collect() function we used, earlier:

{# These produce the same results: #}
{% set posts = craft.entries().section('news').collect() %}
{% set posts = collect(craft.entries().section('news').all()) %}

# Eager-Loading

Eager-loaded elements are stored in a special type of Collection that behaves a bit like an element query—you can safely call .all() on any relational field without worrying about whether it was eager-loaded or not, or use .with() to eager-load another set of nested elements.