<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>{foreach},{foreachelse}</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Smarty Manual">
<link rel="up" href="language.builtin.functions.html" title="Chapter 7. Built-in Functions">
<link rel="prev" href="language.function.config.load.html" title="{config_load}">
<link rel="next" href="language.function.if.html" title="{if},{elseif},{else}">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">{foreach},{foreachelse}</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="language.function.config.load.html">Prev</a> </td>
<th width="60%" align="center">Chapter 7. Built-in Functions</th>
<td width="20%" align="right"> <a accesskey="n" href="language.function.if.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="{foreach},{foreachelse}">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="language.function.foreach"></a>{foreach},{foreachelse}</h2></div></div></div>
<p>
<code class="varname">{foreach}</code> is used to loop over an
<span class="bold"><strong>associative array</strong></span> as well a numerically-indexed array,
unlike <a class="link" href="language.function.section.html" title="{section},{sectionelse}"><code class="varname">{section}</code></a>
which is for looping over <span class="bold"><strong>numerically-indexed arrays only</strong></span>.
The syntax for
<code class="varname">{foreach}</code> is much easier than
<a class="link" href="language.function.section.html" title="{section},{sectionelse}"><code class="varname">{section}</code></a>,
but as a tradeoff it <span class="bold"><strong>can only be used
for a single array</strong></span>. Every <code class="varname">{foreach}</code> tag must be
paired with a closing <code class="varname">{/foreach}</code> tag.
</p>
<div class="informaltable"><table border="1">
<colgroup>
<col align="center">
<col align="center">
<col align="center">
<col align="center">
<col>
</colgroup>
<thead><tr>
<th align="center">Attribute Name</th>
<th align="center">Type</th>
<th align="center">Required</th>
<th align="center">Default</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td align="center">from</td>
<td align="center">array</td>
<td align="center">Yes</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The array you are looping through</td>
</tr>
<tr>
<td align="center">item</td>
<td align="center">string</td>
<td align="center">Yes</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the variable that is the current
element</td>
</tr>
<tr>
<td align="center">key</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the variable that is the current key</td>
</tr>
<tr>
<td align="center">name</td>
<td align="center">string</td>
<td align="center">No</td>
<td align="center"><span class="emphasis"><em>n/a</em></span></td>
<td>The name of the foreach loop for accessing
foreach properties</td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
Required attributes are <em class="parameter"><code>from</code></em> and <em class="parameter"><code>item</code></em>.
</p></li>
<li class="listitem"><p>
The <em class="parameter"><code>name</code></em> of the <code class="varname">{foreach}</code> loop can be anything
you like, made up of letters, numbers and underscores, like
<a class="ulink" href="http://php.net/language.variables" target="_top">PHP variables</a>.
</p></li>
<li class="listitem"><p>
<code class="varname">{foreach}</code> loops can be nested, and the nested
<code class="varname">{foreach}</code> names must be unique from each other.
</p></li>
<li class="listitem"><p>
The <em class="parameter"><code>from</code></em> attribute, usually an array of values,
determines the number of times <code class="varname">{foreach}</code> will loop.
</p></li>
<li class="listitem"><p>
<code class="varname">{foreachelse}</code> is executed when there are no
values in the <em class="parameter"><code>from</code></em> variable.
</p></li>
<li class="listitem">
<p>
<code class="varname">{foreach}</code> loops also have their own variables that handle properties.
These are accessed with:
<a class="link" href="language.variables.smarty.html#language.variables.smarty.loops" title="{$smarty.section}, {$smarty.foreach}">
<em class="parameter"><code>{$smarty.foreach.name.property}</code></em></a> with
<span class="quote">“<span class="quote">name</span>”</span> being the
<em class="parameter"><code>name</code></em> attribute.
</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The <em class="parameter"><code>name</code></em> attribute is only required when
you want to access a <code class="varname">{foreach}</code> property, unlike
<a class="link" href="language.function.section.html" title="{section},{sectionelse}"><code class="varname">{section}</code></a>.
Accessing a <code class="varname">{foreach}</code> property with <em class="parameter"><code>name</code></em>
undefined does not throw an error, but leads to unpredictable results instead.
</p>
</div>
</li>
<li class="listitem"><p>
<code class="varname">{foreach}</code> properties are
<a class="link" href="language.function.foreach.html#foreach.property.index" title=".index"><em class="parameter"><code>index</code></em></a>,
<a class="link" href="language.function.foreach.html#foreach.property.iteration" title=".iteration"><em class="parameter"><code>iteration</code></em></a>,
<a class="link" href="language.function.foreach.html#foreach.property.first" title=".first"><em class="parameter"><code>first</code></em></a>,
<a class="link" href="language.function.foreach.html#foreach.property.last" title=".last"><em class="parameter"><code>last</code></em></a>,
<a class="link" href="language.function.foreach.html#foreach.property.show" title=".show"><em class="parameter"><code>show</code></em></a>,
<a class="link" href="language.function.foreach.html#foreach.property.total" title=".total"><em class="parameter"><code>total</code></em></a>.
</p></li>
</ul></div>
<div class="example">
<a name="id3048158"></a><p class="title"><b>Example 7.5. The <em class="parameter"><code>item</code></em> attribute</b></p>
<div class="example-contents">
<pre class="programlisting">
<?php
$arr = array(1000, 1001, 1002);
$smarty->assign('myArray', $arr);
?>
</pre>
<p>Template to output <em class="parameter"><code>$myArray</code></em> in an un-ordered list</p>
<pre class="programlisting">
<ul>
{foreach from=$myArray item=foo}
<li>{$foo}</li>
{/foreach}
</ul>
</pre>
<p>
The above example will output:
</p>
<pre class="screen">
<ul>
<li>1000</li>
<li>1001</li>
<li>1002</li>
</ul>
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id3048211"></a><p class="title"><b>Example 7.6. Demonstrates the <em class="parameter"><code>item</code></em> and <em class="parameter"><code>key</code></em> attributes</b></p>
<div class="example-contents">
<pre class="programlisting">
<?php
$arr = array(9 => 'Tennis', 3 => 'Swimming', 8 => 'Coding');
$smarty->assign('myArray', $arr);
?>
</pre>
<p>Template to output <em class="parameter"><code>$myArray</code></em> as key/val pair,
like PHP's <a class="ulink" href="http://php.net/foreach" target="_top"><code class="varname">foreach</code></a>.</p>
<pre class="programlisting">
<ul>
{foreach from=$myArray key=k item=v}
<li>{$k}: {$v}</li>
{/foreach}
</ul>
</pre>
<p>
The above example will output:
</p>
<pre class="screen">
<ul>
<li>9: Tennis</li>
<li>3: Swimming</li>
<li>8: Coding</li>
</ul>
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id3048279"></a><p class="title"><b>Example 7.7. {foreach} with associative <em class="parameter"><code>item</code></em> attribute</b></p>
<div class="example-contents">
<pre class="programlisting">
<?php
$items_list = array(23 => array('no' => 2456, 'label' => 'Salad'),
96 => array('no' => 4889, 'label' => 'Cream')
);
$smarty->assign('items', $items_list);
?>
</pre>
<p>Template to output <em class="parameter"><code>$items</code></em> with
<em class="parameter"><code>$myId</code></em> in the url</p>
<pre class="programlisting">
<ul>
{foreach from=$items key=myId item=i}
<li><a href="item.php?id={$myId}">{$i.no}: {$i.label}</li>
{/foreach}
</ul>
</pre>
<p>
The above example will output:
</p>
<pre class="screen">
<ul>
<li><a href="item.php?id=23">2456: Salad</li>
<li><a href="item.php?id=96">4889: Cream</li>
</ul>
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id3048342"></a><p class="title"><b>Example 7.8. {foreach} with nested <em class="parameter"><code>item</code></em> and <em class="parameter"><code>key</code></em></b></p>
<div class="example-contents">
<p>Assign an array to Smarty, the key contains the key for each looped value.</p>
<pre class="programlisting">
<?php
$smarty->assign('contacts', array(
array('phone' => '1',
'fax' => '2',
'cell' => '3'),
array('phone' => '555-4444',
'fax' => '555-3333',
'cell' => '760-1234')
));
?>
</pre>
<p>The template to output <em class="parameter"><code>$contact</code></em>.</p>
<pre class="programlisting">
{foreach name=outer item=contact from=$contacts}
<hr />
{foreach key=key item=item from=$contact}
{$key}: {$item}<br />
{/foreach}
{/foreach}
</pre>
<p>
The above example will output:
</p>
<pre class="screen">
<hr />
phone: 1<br />
fax: 2<br />
cell: 3<br />
<hr />
phone: 555-4444<br />
fax: 555-3333<br />
cell: 760-1234<br />
</pre>
</div>
</div>
<br class="example-break"><div class="example">
<a name="id3048419"></a><p class="title"><b>Example 7.9. Database example with {foreachelse}</b></p>
<div class="example-contents">
<p>A database (eg PEAR or ADODB) example of a search script, the query results assigned to Smarty</p>
<pre class="programlisting">
<?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) );
?>
</pre>
<p>The template which display <span class="quote">“<span class="quote">None found</span>”</span>
if no results with <code class="varname">{foreachelse}</code>.</p>
<pre class="programlisting">
{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}
</pre>
</div>
</div>
<br class="example-break"><div class="sect2" title=".index">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.index"></a>.index</h3></div></div></div>
<p>
<em class="parameter"><code>index</code></em> contains the current array index, starting with zero.
</p>
<div class="example">
<a name="id3048492"></a><p class="title"><b>Example 7.10. <em class="parameter"><code>index</code></em> example</b></p>
<div class="example-contents"><pre class="programlisting">
{* 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>
</pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" title=".iteration">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.iteration"></a>.iteration</h3></div></div></div>
<p>
<em class="parameter"><code>iteration</code></em> contains the current loop iteration and always
starts at one, unlike <a class="link" href="language.function.foreach.html#foreach.property.index" title=".index"><em class="parameter"><code>index</code></em></a>.
It is incremented by one on each iteration.
</p>
<div class="example">
<a name="id3048551"></a><p class="title"><b>Example 7.11. <em class="parameter"><code>iteration</code></em> and <em class="parameter"><code>index</code></em> example</b></p>
<div class="example-contents"><pre class="programlisting">
{* 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}
</pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" title=".first">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.first"></a>.first</h3></div></div></div>
<p>
<em class="parameter"><code>first</code></em> is <code class="constant">TRUE</code> if the current <code class="varname">{foreach}</code>
iteration is the initial one.
</p>
<div class="example">
<a name="id3048609"></a><p class="title"><b>Example 7.12. <em class="parameter"><code>first</code></em> property example</b></p>
<div class="example-contents"><pre class="programlisting">
{* 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>
</pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" title=".last">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.last"></a>.last</h3></div></div></div>
<p>
<em class="parameter"><code>last</code></em> is set to <code class="constant">TRUE</code> if the current
<code class="varname">{foreach}</code> iteration is the final one.
</p>
<div class="example">
<a name="id3048664"></a><p class="title"><b>Example 7.13. <em class="parameter"><code>last</code></em> property example</b></p>
<div class="example-contents"><pre class="programlisting">
{* 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}
</pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" title=".show">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.show"></a>.show</h3></div></div></div>
<p>
<em class="parameter"><code>show</code></em> is used as a parameter to <code class="varname">{foreach}</code>.
<em class="parameter"><code>show</code></em> is a boolean value. If
<code class="constant">FALSE</code>, the <code class="varname">{foreach}</code> will not be displayed.
If there is a <code class="varname">{foreachelse}</code> present, that will be alternately displayed.
</p>
</div>
<div class="sect2" title=".total">
<div class="titlepage"><div><div><h3 class="title">
<a name="foreach.property.total"></a>.total</h3></div></div></div>
<p>
<em class="parameter"><code>total</code></em> contains the number of iterations that this
<code class="varname">{foreach}</code> will loop.
This can be used inside or after the <code class="varname">{foreach}</code>.
</p>
<div class="example">
<a name="id3048761"></a><p class="title"><b>Example 7.14. <em class="parameter"><code>total</code></em> property example</b></p>
<div class="example-contents"><pre class="programlisting">
{* 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}
</pre></div>
</div>
<br class="example-break"><p>
See also <a class="link" href="language.function.section.html" title="{section},{sectionelse}"><code class="varname">{section}</code></a>
and <a class="link" href="language.variables.smarty.html#language.variables.smarty.loops" title="{$smarty.section}, {$smarty.foreach}"><em class="parameter"><code>$smarty.foreach</code></em></a>.
</p>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="language.function.config.load.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="language.builtin.functions.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="language.function.if.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">{config_load} </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> {if},{elseif},{else}</td>
</tr>
</table>
</div>
</body>
</html>
