<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<refentry xml:id="function.array-walk" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>array_walk</refname>

<refpurpose>Apply a user supplied function to every member of an array</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>true</type><methodname>array_walk</methodname>

<methodparam><type class="union"><type>array</type><type>object</type></type><parameter role="reference">array</parameter></methodparam>

<methodparam><type>callable</type><parameter>callback</parameter></methodparam>

<methodparam choice="opt"><type>mixed</type><parameter>arg</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<simpara>

Applies the user-defined <parameter>callback</parameter> function to each

element of the <parameter>array</parameter> array.

</simpara>

<para>

<function>array_walk</function> is not affected by the internal array

pointer of <parameter>array</parameter>. <function>array_walk</function>

will walk through the entire array regardless of pointer position.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>array</parameter></term>

<listitem>

<para>

The input array.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<para>

Typically, <parameter>callback</parameter> takes on two parameters.

The <parameter>array</parameter> parameter's value being the first, and

the key/index second.

</para>

<note>

<para>

If <parameter>callback</parameter> needs to be working with the

actual values of the array, specify the first parameter of

<parameter>callback</parameter> as a

<link linkend="language.references">reference</link>. Then,

any changes made to those elements will be made in the

original array itself.

</para>

</note>

<note>

<para>

Many internal functions (for example <function>strtolower</function>)

will throw if more than the expected number of arguments

are passed in and are not usable directly as a

<parameter>callback</parameter>.

</para>

</note>

<para>

Only the values of the <parameter>array</parameter> 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.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>arg</parameter></term>

<listitem>

<para>

If the optional <parameter>arg</parameter> parameter is supplied,

it will be passed as the third parameter to the

<parameter>callback</parameter>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.true.always;

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

As of PHP 7.1.0, an <classname>ArgumentCountError</classname> will be thrown if the <parameter>callback</parameter> function

requires more than 2 parameters (the value and key of the array member),

or more than 3 parameters if the <parameter>arg</parameter> is also passed.

Previously, in this case

an error of level <link linkend="errorfunc.constants">E_WARNING</link> would be generated each time

<function>array_walk</function> calls <parameter>callback</parameter>.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

&return.type.true;

<row>

<entry>8.0.0</entry>

<entry>

If <parameter>callback</parameter> expects the second or third parameter to be passed

by reference, this function will now emit an <constant>E_WARNING</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>array_walk</function> example</title>

<programlisting role="php">

<![CDATA[

<?php

$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");

function test_alter(&$item1, $key, $prefix)

{

$item1 = "$prefix: $item1";

}

function test_print($item2, $key)

{

echo "$key. $item2\n";

}

echo "Before ...:\n";

array_walk($fruits, 'test_print');

array_walk($fruits, 'test_alter', 'fruit');

echo "... and after:\n";

array_walk($fruits, 'test_print');

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

Before ...:

d. lemon

a. orange

b. banana

c. apple

... and after:

d. fruit: lemon

a. fruit: orange

b. fruit: banana

c. fruit: apple

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>array_walk</function> example using anonymous function</title>

<programlisting role="php">

<![CDATA[

<?php

$elements = ['a', 'b', 'c'];

array_walk($elements, function ($value, $key) {

echo "{$key} => {$value}\n";

});

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

0 => a

1 => b

2 => c

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>array_walk_recursive</function></member>

<member><function>iterator_apply</function></member>

<member><function>list</function></member>

<member><function>each</function></member>

<member><function>call_user_func_array</function></member>

<member><function>array_map</function></member>

<member>&foreach;</member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->