1``for``
2=======
3
4Loop over each item in a sequence. For example, to display a list of users
5provided in a variable called ``users``:
6
7.. code-block:: html+twig
8
9    <h1>Members</h1>
10    <ul>
11        {% for user in users %}
12            <li>{{ user.username|e }}</li>
13        {% endfor %}
14    </ul>
15
16.. note::
17
18    A sequence can be either an array or an object implementing the
19    ``Traversable`` interface.
20
21If you do need to iterate over a sequence of numbers, you can use the ``..``
22operator:
23
24.. code-block:: twig
25
26    {% for i in 0..10 %}
27        * {{ i }}
28    {% endfor %}
29
30The above snippet of code would print all numbers from 0 to 10.
31
32It can be also useful with letters:
33
34.. code-block:: twig
35
36    {% for letter in 'a'..'z' %}
37        * {{ letter }}
38    {% endfor %}
39
40The ``..`` operator can take any expression at both sides:
41
42.. code-block:: twig
43
44    {% for letter in 'a'|upper..'z'|upper %}
45        * {{ letter }}
46    {% endfor %}
47
48.. tip:
49
50    If you need a step different from 1, you can use the ``range`` function
51    instead.
52
53The `loop` variable
54-------------------
55
56Inside of a ``for`` loop block you can access some special variables:
57
58===================== =============================================================
59Variable              Description
60===================== =============================================================
61``loop.index``        The current iteration of the loop. (1 indexed)
62``loop.index0``       The current iteration of the loop. (0 indexed)
63``loop.revindex``     The number of iterations from the end of the loop (1 indexed)
64``loop.revindex0``    The number of iterations from the end of the loop (0 indexed)
65``loop.first``        True if first iteration
66``loop.last``         True if last iteration
67``loop.length``       The number of items in the sequence
68``loop.parent``       The parent context
69===================== =============================================================
70
71.. code-block:: twig
72
73    {% for user in users %}
74        {{ loop.index }} - {{ user.username }}
75    {% endfor %}
76
77.. note::
78
79    The ``loop.length``, ``loop.revindex``, ``loop.revindex0``, and
80    ``loop.last`` variables are only available for PHP arrays, or objects that
81    implement the ``Countable`` interface. They are also not available when
82    looping with a condition.
83
84Adding a condition
85------------------
86
87.. tip::
88
89    As of Twig 2.10, use the :doc:`filter <../filters/filter>` filter instead,
90    or an ``if`` condition inside the ``for`` body (if your condition depends on
91    a variable updated inside the loop and you are not using the ``loop``
92    variable).
93
94Unlike in PHP, it's not possible to ``break`` or ``continue`` in a loop. You
95can however filter the sequence during iteration which allows you to skip
96items. The following example skips all the users which are not active:
97
98.. code-block:: html+twig
99
100    <ul>
101        {% for user in users if user.active %}
102            <li>{{ user.username|e }}</li>
103        {% endfor %}
104    </ul>
105
106The advantage is that the special loop variable will count correctly thus not
107counting the users not iterated over. Keep in mind that properties like
108``loop.last`` will not be defined when using loop conditions.
109
110.. note::
111
112    Using the ``loop`` variable within the condition is not recommended as it
113    will probably not be doing what you expect it to. For instance, adding a
114    condition like ``loop.index > 4`` won't work as the index is only
115    incremented when the condition is true (so the condition will never
116    match).
117
118The `else` Clause
119-----------------
120
121If no iteration took place because the sequence was empty, you can render a
122replacement block by using ``else``:
123
124.. code-block:: html+twig
125
126    <ul>
127        {% for user in users %}
128            <li>{{ user.username|e }}</li>
129        {% else %}
130            <li><em>no user found</em></li>
131        {% endfor %}
132    </ul>
133
134Iterating over Keys
135-------------------
136
137By default, a loop iterates over the values of the sequence. You can iterate
138on keys by using the ``keys`` filter:
139
140.. code-block:: html+twig
141
142    <h1>Members</h1>
143    <ul>
144        {% for key in users|keys %}
145            <li>{{ key }}</li>
146        {% endfor %}
147    </ul>
148
149Iterating over Keys and Values
150------------------------------
151
152You can also access both keys and values:
153
154.. code-block:: html+twig
155
156    <h1>Members</h1>
157    <ul>
158        {% for key, user in users %}
159            <li>{{ key }}: {{ user.username|e }}</li>
160        {% endfor %}
161    </ul>
162
163Iterating over a Subset
164-----------------------
165
166You might want to iterate over a subset of values. This can be achieved using
167the :doc:`slice <../filters/slice>` filter:
168
169.. code-block:: html+twig
170
171    <h1>Top Ten Members</h1>
172    <ul>
173        {% for user in users|slice(0, 10) %}
174            <li>{{ user.username|e }}</li>
175        {% endfor %}
176    </ul>
177