New in Twig 4.0: A New for Loop for Twig 4.0

The Problem: A loop Variable Full of Holes

In Twig 3, the values exposed by loop are computed once, before the loop starts. That detail leaks into your templates: loop.last, loop.length, loop.revindex, and loop.revindex0 only exist when the sequence can be counted upfront, an array or a Countable object. Loop over a generator or a database result iterator, and they quietly disappear:

{# "users" is a generator, not an array #}
{% for user in users %}
    {{ user.username }}{% if not loop.last %}, {% endif %}
{% endfor %}

{# Twig 3 outputs a trailing comma: Lucas, Hélène, Thomas, #}

It works on your machine, where users is a plain array. Then someone optimizes the code to stream users straight from the database, and production greets you with a trailing comma: loop.last evaluates to null, so the condition is always true. With strict_variables enabled, you get an error instead, but not a helpful one:

Key "last" for sequence/mapping with keys "parent, index0, index, first" does not exist in "user_list.html.twig" at line 4.

Not great either way. Twig 4.0 closes this gap, and takes the opportunity to make the loop context much more capable.

loop.last Now Works with Any Iterator

In Twig 4, the loop reads one item ahead, so loop.last is always available, whatever you iterate on: arrays, generators, any Traversable. The snippet above renders Lucas, Hélène, Thomas. No trailing comma, no surprise.

What about loop.length? Counting a generator would mean consuming it, so it still requires a countable sequence; same for loop.revindex and loop.revindex0. But instead of behaving like undefined variables, they now fail with an error that tells you what is actually going on:

The "loop.length" variable is not defined as the loop iterates on a non-countable iterator in "user_list.html.twig" at line 4.

Two related fixes complete the picture: loop behaves correctly in the else clause of a loop, and IteratorAggregate objects are iterated as expected.

loop.previous and loop.next

Reading one item ahead enables more than a working loop.last. Two new variables give you access to the values surrounding the current one:

{% for value in values %}
    {% if not loop.first and value > loop.previous %}
        The value increased!
    {% endif %}
    {{ value }}
{% endfor %}

They work with generators too.

Grouping with loop.changed()

You know this template; we have all written it:

{# Twig 3 #}
{% set previousCategory = null %}
{% for entry in entries %}
    {% if entry.category != previousCategory %}
        <h2>{{ entry.category }}</h2>
        {% set previousCategory = entry.category %}
    {% endif %}
    <p>{{ entry.message }}</p>
{% endfor %}

Tracking the previous category by hand works, but it is super verbose. The new loop.changed() method returns true whenever it is called with a value different from the previous call:

{# Twig 4 #}
{% for entry in entries %}
    {% if loop.changed(entry.category) %}
        <h2>{{ entry.category }}</h2>
    {% endif %}
    <p>{{ entry.message }}</p>
{% endfor %}

Cycling with loop.cycle()

Alternating between values used to go through the global cycle() function, which needs to be told the current position explicitly:

{# Twig 3 #}
{% for row in rows %}
    <li class="{{ cycle(['odd', 'even'], loop.index0) }}">{{ row }}</li>
{% endfor %}

The loop now does it natively and keeps track of the position for you:

{# Twig 4 #}
{% for row in rows %}
    <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
{% endfor %}

The if Condition Is Back

Twig 3.0 removed the if condition on for tags. The filter filter is supposed to be a replacement but as it runs before the loop starts, the condition cannot depend on something that changes inside the loop body, nor on the loop variable itself. Twig 4 brings the condition back:

{% for user in users if user.active %}
    <li>{{ user.username }}</li>
{% endfor %}

My advice: use |filter when the condition only depends on each item, and if when it depends on the loop state or on variables updated in the body:

{% set stopOnFabien = false %}
{% for user in users if not stopOnFabien %}
    - {{ user }}
    {% set stopOnFabien = user == 'Fabien' %}
{% endfor %}

Recursive Loops

Jinja, Twig's Python cousin, has had recursive loops forever. In Twig, we emulated them with a macro calling itself through _self:

{# Twig 3 #}
{% macro menu(items) %}
    <ul>
        {% for item in items %}
            <li>{{ item.title }}
                {% if item.children %}
                    {{ _self.menu(item.children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{{ _self.menu(sitemap) }}

It works, but defining a macro to render a sitemap always felt like too much ceremony to me. Twig 4 makes recursion part of the loop itself: call the loop() function with a nested sequence and the loop body is re-executed for it:

{# Twig 4 #}
<ul class="sitemap">
    {% for item in sitemap %}
        <li>{{ item.title }}
            {% if item.children %}
                <ul>{{ loop(item.children) }}</ul>
            {% endif %}
        </li>
    {% endfor %}
</ul>

Two companion variables, loop.depth and loop.depth0, expose the current nesting level. And because infinite recursion is always one bug away, a built-in guard stops it with a Nesting level too deep. error after 50 levels, before it takes your server down with it.

The Upgrade Path

The for rework introduces no deprecations on the 3.x branch: a template that runs deprecation-free on Twig 3 renders identically on Twig 4.0, with the lone exception that reading loop.length, loop.revindex, or loop.revindex0 on a non-countable iterator now raises a clear error instead of producing empty output. The new loop features are exclusive to Twig 4.0, available today as an alpha release; one more reason to give it a spin.