Matthias Andreas Benkard | 12a5735 | 2021-12-28 18:02:04 +0100 | [diff] [blame^] | 1 | ``for`` |
| 2 | ======= |
| 3 | |
| 4 | Loop over each item in a sequence. For example, to display a list of users |
| 5 | provided 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 | |
| 21 | If you do need to iterate over a sequence of numbers, you can use the ``..`` |
| 22 | operator: |
| 23 | |
| 24 | .. code-block:: twig |
| 25 | |
| 26 | {% for i in 0..10 %} |
| 27 | * {{ i }} |
| 28 | {% endfor %} |
| 29 | |
| 30 | The above snippet of code would print all numbers from 0 to 10. |
| 31 | |
| 32 | It can be also useful with letters: |
| 33 | |
| 34 | .. code-block:: twig |
| 35 | |
| 36 | {% for letter in 'a'..'z' %} |
| 37 | * {{ letter }} |
| 38 | {% endfor %} |
| 39 | |
| 40 | The ``..`` 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 | |
| 53 | The `loop` variable |
| 54 | ------------------- |
| 55 | |
| 56 | Inside of a ``for`` loop block you can access some special variables: |
| 57 | |
| 58 | ===================== ============================================================= |
| 59 | Variable 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. |
| 82 | |
| 83 | The `else` Clause |
| 84 | ----------------- |
| 85 | |
| 86 | If no iteration took place because the sequence was empty, you can render a |
| 87 | replacement block by using ``else``: |
| 88 | |
| 89 | .. code-block:: html+twig |
| 90 | |
| 91 | <ul> |
| 92 | {% for user in users %} |
| 93 | <li>{{ user.username|e }}</li> |
| 94 | {% else %} |
| 95 | <li><em>no user found</em></li> |
| 96 | {% endfor %} |
| 97 | </ul> |
| 98 | |
| 99 | Iterating over Keys |
| 100 | ------------------- |
| 101 | |
| 102 | By default, a loop iterates over the values of the sequence. You can iterate |
| 103 | on keys by using the ``keys`` filter: |
| 104 | |
| 105 | .. code-block:: html+twig |
| 106 | |
| 107 | <h1>Members</h1> |
| 108 | <ul> |
| 109 | {% for key in users|keys %} |
| 110 | <li>{{ key }}</li> |
| 111 | {% endfor %} |
| 112 | </ul> |
| 113 | |
| 114 | Iterating over Keys and Values |
| 115 | ------------------------------ |
| 116 | |
| 117 | You can also access both keys and values: |
| 118 | |
| 119 | .. code-block:: html+twig |
| 120 | |
| 121 | <h1>Members</h1> |
| 122 | <ul> |
| 123 | {% for key, user in users %} |
| 124 | <li>{{ key }}: {{ user.username|e }}</li> |
| 125 | {% endfor %} |
| 126 | </ul> |
| 127 | |
| 128 | Iterating over a Subset |
| 129 | ----------------------- |
| 130 | |
| 131 | You might want to iterate over a subset of values. This can be achieved using |
| 132 | the :doc:`slice <../filters/slice>` filter: |
| 133 | |
| 134 | .. code-block:: html+twig |
| 135 | |
| 136 | <h1>Top Ten Members</h1> |
| 137 | <ul> |
| 138 | {% for user in users|slice(0, 10) %} |
| 139 | <li>{{ user.username|e }}</li> |
| 140 | {% endfor %} |
| 141 | </ul> |