Smarty Manual
Prev | Chapter 7. Built-in Functions | Next

# {foreach},{foreachelse}

`{foreach}` is used to loop over an associative array as well a numerically-indexed array, unlike `{section}` which is for looping over numerically-indexed arrays only. The syntax for `{foreach}` is much easier than `{section}`, but as a tradeoff it can only be used for a single array. Every `{foreach}` tag must be paired with a closing `{/foreach}` tag.

Attribute Name | Type | Required | Default | Description
--- | --- | --- | --- | ---
from | array | Yes | n/a | The array you are looping through
item | string | Yes | n/a | The name of the variable that is the current element
key | string | No | n/a | The name of the variable that is the current key
name | string | No | n/a | The name of the foreach loop for accessing foreach properties

- Required attributes are `from` and `item`.

- The `name` of the `{foreach}` loop can be anything you like, made up of letters, numbers and underscores, like PHP variables.

- `{foreach}` loops can be nested, and the nested `{foreach}` names must be unique from each other.

- The `from` attribute, usually an array of values, determines the number of times `{foreach}` will loop.

- `{foreachelse}` is executed when there are no values in the `from` variable.

- `{foreach}` loops also have their own variables that handle properties. These are accessed with: `{$smarty.foreach.name.property}` with "name" being the `name` attribute.

  > Note: The `name` attribute is only required when you want to access a `{foreach`} property, unlike `{section}`. Accessing a `{foreach}` property with `name` undefined does not throw an error, but leads to unpredictable results instead.

- `{foreach}` properties are `index`, `iteration`, `first`, `last`, `show`, `total`.

Example 7-5. The `item` attribute
`<?php $arr = array(1000, 1001, 1002); $smarty->assign('myArray', $arr); ?>`
Template to output `$myArray` in an un-ordered list
    <ul>
    {foreach from=$myArray item=foo}
        <li>{$foo}</li>
    {/foreach}
    </ul>
The above example will output:
    <ul>
        <li>1000</li>
        <li>1001</li>
        <li>1002</li>
    </ul>

Example 7-6. Demonstrates the `item` and `key` attributes
`<?php $arr = array(9 => 'Tennis', 3 => 'Swimming', 8 => 'Coding'); $smarty->assign('myArray', $arr); ?>`
Template to output `$myArray` as key/val pair, like PHP's `foreach`.
    <ul>
    {foreach from=$myArray key=k item=v}
       <li>{$k}: {$v}</li>
    {/foreach}
    </ul>
The above example will output:
    <ul>
        <li>9: Tennis</li>
        <li>3: Swimming</li>
        <li>8: Coding</li>
    </ul>

Example 7-7. {foreach} with associative `item` attribute
`<?php $items_list = array(23 => array('no' => 2456, 'label' => 'Salad'), 96 => array('no' => 4889, 'label' => 'Cream') ); $smarty->assign('items', $items_list); ?>`
Template to output `$items` with `$myId` in the url
    <ul>
    {foreach from=$items key=myId item=i}
      <li><a href="item.php?id={$myId}">{$i.no}: {$i.label}</li>
    {/foreach}
    </ul>
The above example will output:
    <ul>
      <li><a href="item.php?id=23">2456: Salad</li>
      <li><a href="item.php?id=96">4889: Cream</li>
    </ul>

Example 7-8. {foreach} with nested `item` and `key` Assign an array to Smarty, the key contains the key for each looped value.
`<?php $smarty->assign('contacts', array( array('phone' => '1', 'fax' => '2', 'cell' => '3'), array('phone' => '555-4444', 'fax' => '555-3333', 'cell' => '760-1234') )); ?>`
The template to output `$contact`.
    {foreach name=outer item=contact from=$contacts}
      <hr />
      {foreach key=key item=item from=$contact}
        {$key}: {$item}<br />
      {/foreach}
    {/foreach}
The above example will output:
    <hr />
      phone: 1<br />
      fax: 2<br />
      cell: 3<br />
    <hr />
      phone: 555-4444<br />
      fax: 555-3333<br />
      cell: 760-1234<br />

Example 7-9. Database example with {foreachelse} A database (eg PEAR or ADODB) example of a search script, the query results assigned to Smarty
`<?php $search_condition = "where name like '$foo%' "; $sql = 'select contact_id, name, nick from contacts '.$search_condition.' order by name'; $smarty->assign('results', $db->getAssoc($sql) ); ?>`
The template which display "None found" if no results with `{foreachelse}`.
    {foreach key=cid item=con from=$results}
        <a href="contact.php?contact_id={$cid}">{$con.name} - {$con.nick}</a><br />
    {foreachelse}
        No items were found in the search
    {/foreach}

## .index

`index` contains the current array index, starting with zero.

Example 7-10. `index` example
`{* The header block is output every five rows *} <table> {foreach from=$items key=myId item=i name=foo} {if $smarty.foreach.foo.index % 5 == 0} <tr><th>Title</th></tr> {/if} <tr><td>{$i.label}</td></tr> {/foreach} </table>`

## .iteration

`iteration` contains the current loop iteration and always starts at one, unlike `index`. It is incremented by one on each iteration.

Example 7-11. `iteration` and `index` example
`{* this will output 0|1, 1|2, 2|3, ... etc *} {foreach from=$myArray item=i name=foo} {$smarty.foreach.foo.index}|{$smarty.foreach.foo.iteration}, {/foreach}`

## .first

`first` is `TRUE` if the current `{foreach}` iteration is the initial one.

Example 7-12. `first` property example
`{* show LATEST on the first item, otherwise the id *} <table> {foreach from=$items key=myId item=i name=foo} <tr> <td>{if $smarty.foreach.foo.first}LATEST{else}{$myId}{/if}</td> <td>{$i.label}</td> </tr> {/foreach} </table>`

## .last

`last` is set to `TRUE` if the current `{foreach}` iteration is the final one.

Example 7-13. `last` property example
`{* Add horizontal rule at end of list *} {foreach from=$items key=part_id item=prod name=products} <a href="#{$part_id}">{$prod}</a>{if $smarty.foreach.products.last}<hr>{else},{/if} {foreachelse} ... content ... {/foreach}`

## .show

`show` is used as a parameter to `{foreach}`. `show` is a boolean value. If `FALSE`, the `{foreach}` will not be displayed. If there is a `{foreachelse}` present, that will be alternately displayed.

## .total

`total` contains the number of iterations that this `{foreach}` will loop. This can be used inside or after the `{foreach}`.

Example 7-14. `total` property example
`{* show rows returned at end *} {foreach from=$items key=part_id item=prod name=foo} {$prod.name><hr/> {if $smarty.foreach.foo.last} <div id="total">{$smarty.foreach.foo.total} items</div> {/if} {foreachelse} ... something else ... {/foreach}`

See also `{section}` and `$smarty.foreach`.

Prev | Home | Next
{config_load} | Up | {if},{elseif},{else}