array-walk.xml

<?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 a warning if more than the expected number of argument
          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
-->