<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Apply a user function to every member of an array</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.array-walk-recursive.html">array_walk_recursive</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.array.html">array</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.array-walk" class="refentry">
<div class="refnamediv">
<h1 class="refname">array_walk</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">array_walk</span> — <span class="dc-title">Apply a user function to every member of an array</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.array-walk-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>array_walk</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$array</code></span>
, <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$callback</code></span>
[, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$userdata</code><span class="initializer"> = <strong><code>NULL</code></strong></span></span>
] )</div>
<p class="simpara">
Applies the user-defined <em><code class="parameter">callback</code></em> function to each
element of the <em><code class="parameter">array</code></em> array.
</p>
<p class="para">
<span class="function"><strong>array_walk()</strong></span> is not affected by the internal array
pointer of <em><code class="parameter">array</code></em>. <span class="function"><strong>array_walk()</strong></span>
will walk through the entire array regardless of pointer position.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.array-walk-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">array</code></em></span>
<dd>
<p class="para">
The input array.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">callback</code></em></span>
<dd>
<p class="para">
Typically, <em><code class="parameter">callback</code></em> takes on two parameters.
The <em><code class="parameter">array</code></em> parameter's value being the first, and
the key/index second.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If <em><code class="parameter">callback</code></em> needs to be working with the
actual values of the array, specify the first parameter of
<em><code class="parameter">callback</code></em> as a
<a href="language.references.html" class="link">reference</a>. Then,
any changes made to those elements will be made in the
original array itself.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Many internal functions (for example <span class="function"><a href="function.strtolower.html" class="function">strtolower()</a></span>)
will throw a warning if more than the expected number of argument
are passed in and are not usable directly as a
<em><code class="parameter">callback</code></em>.
</p>
</p></blockquote>
<p class="para">
Only the values of the <em><code class="parameter">array</code></em> may potentially be
changed; its structure cannot be altered, i.e., the programmer cannot
add, unset or reorder elements. If the callback does not respect this
requirement, the behavior of this function is undefined, and
unpredictable.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">userdata</code></em></span>
<dd>
<p class="para">
If the optional <em><code class="parameter">userdata</code></em> parameter is supplied,
it will be passed as the third parameter to the
<em><code class="parameter">callback</code></em>.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.array-walk-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 errors" id="refsect1-function.array-walk-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
If function <em><code class="parameter">callback</code></em> requires more parameters than
given to it, an error of level <a href="errorfunc.constants.html" class="link">
E_WARNING</a> will be generated each time <span class="function"><strong>array_walk()</strong></span>
calls <em><code class="parameter">callback</code></em>.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.array-walk-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4998">
<p><strong>Example #1 <span class="function"><strong>array_walk()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$fruits </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"d" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"lemon"</span><span style="color: #007700">, </span><span style="color: #DD0000">"a" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"orange"</span><span style="color: #007700">, </span><span style="color: #DD0000">"b" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"banana"</span><span style="color: #007700">, </span><span style="color: #DD0000">"c" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"apple"</span><span style="color: #007700">);<br /><br />function </span><span style="color: #0000BB">test_alter</span><span style="color: #007700">(&</span><span style="color: #0000BB">$item1</span><span style="color: #007700">, </span><span style="color: #0000BB">$key</span><span style="color: #007700">, </span><span style="color: #0000BB">$prefix</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #0000BB">$item1 </span><span style="color: #007700">= </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$prefix</span><span style="color: #DD0000">: </span><span style="color: #0000BB">$item1</span><span style="color: #DD0000">"</span><span style="color: #007700">;<br />}<br /><br />function </span><span style="color: #0000BB">test_print</span><span style="color: #007700">(</span><span style="color: #0000BB">$item2</span><span style="color: #007700">, </span><span style="color: #0000BB">$key</span><span style="color: #007700">)<br />{<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$key</span><span style="color: #DD0000">. </span><span style="color: #0000BB">$item2</span><span style="color: #DD0000"><br />\n"</span><span style="color: #007700">;<br />}<br /><br />echo </span><span style="color: #DD0000">"Before ...:\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">array_walk</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruits</span><span style="color: #007700">, </span><span style="color: #DD0000">'test_print'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">array_walk</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruits</span><span style="color: #007700">, </span><span style="color: #DD0000">'test_alter'</span><span style="color: #007700">, </span><span style="color: #DD0000">'fruit'</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"... and after:\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">array_walk</span><span style="color: #007700">(</span><span style="color: #0000BB">$fruits</span><span style="color: #007700">, </span><span style="color: #DD0000">'test_print'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Before ...:
d. lemon
a. orange
b. banana
c. apple
... and after:
d. fruit: lemon
a. fruit: orange
b. fruit: banana
c. fruit: apple
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.array-walk-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.array-walk-recursive.html" class="function" rel="rdfs-seeAlso">array_walk_recursive()</a> - Apply a user function recursively to every member of an array</span></li>
<li class="member"> <span class="function"><a href="function.iterator-apply.html" class="function" rel="rdfs-seeAlso">iterator_apply()</a> - Call a function for every element in an iterator</span></li>
<li class="member"> <span class="function"><a href="function.list.html" class="function" rel="rdfs-seeAlso">list()</a> - Assign variables as if they were an array</span></li>
<li class="member"> <span class="function"><a href="function.each.html" class="function" rel="rdfs-seeAlso">each()</a> - Return the current key and value pair from an array and advance the array cursor</span></li>
<li class="member"> <span class="function"><a href="function.call-user-func-array.html" class="function" rel="rdfs-seeAlso">call_user_func_array()</a> - Call a callback with an array of parameters</span></li>
<li class="member"> <span class="function"><a href="function.array-map.html" class="function" rel="rdfs-seeAlso">array_map()</a> - Applies the callback to the elements of the given arrays</span></li>
<li class="member">information about the <a href="language.pseudo-types.html#language.types.callback" class="link">callback</a> type</li>
<li class="member"><a href="control-structures.foreach.html" class="link">foreach</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.array-walk-recursive.html">array_walk_recursive</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.array.html">array</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
