<!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>Callbacks</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.types.null.html">NULL</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.pseudo-types.html">Pseudo-types and variables used in this documentation</a></div> <div class="up"><a href="language.types.html">Types</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="language.types.callable" class="sect1"> <h2 class="title">Callbacks</h2> <p class="para"> Callbacks can be denoted by <span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> type hint as of PHP 5.4. This documentation used <span class="type"><a href="language.pseudo-types.html#language.types.callback" class="type callback">callback</a></span> type information for the same purpose. </p> <p class="para"> Some functions like <span class="function"><a href="function.call-user-func.html" class="function">call_user_func()</a></span> or <span class="function"><a href="function.usort.html" class="function">usort()</a></span> accept user-defined callback functions as a parameter. Callback functions can not only be simple functions, but also <span class="type"><a href="language.types.object.html" class="type object">object</a></span> methods, including static class methods. </p> <div class="sect2" id="language.types.callable.passing"> <h3 class="title">Passing</h3> <p class="para"> A PHP function is passed by its name as a <span class="type"><a href="language.types.string.html" class="type string">string</a></span>. Any built-in or user-defined function can be used, except language constructs such as: <span class="function"><a href="function.array.html" class="function">array()</a></span>, <span class="function"><a href="function.echo.html" class="function">echo</a></span>, <span class="function"><a href="function.empty.html" class="function">empty()</a></span>, <span class="function"><a href="function.eval.html" class="function">eval()</a></span>, <span class="function"><a href="function.exit.html" class="function">exit()</a></span>, <span class="function"><a href="function.isset.html" class="function">isset()</a></span>, <span class="function"><a href="function.list.html" class="function">list()</a></span>, <span class="function"><a href="function.print.html" class="function">print</a></span> or <span class="function"><a href="function.unset.html" class="function">unset()</a></span>. </p> <p class="para"> A method of an instantiated <span class="type"><a href="language.types.object.html" class="type object">object</a></span> is passed as an <span class="type"><a href="language.types.array.html" class="type array">array</a></span> containing an <span class="type"><a href="language.types.object.html" class="type object">object</a></span> at index 0 and the method name at index 1. </p> <p class="para"> Static class methods can also be passed without instantiating an <span class="type"><a href="language.types.object.html" class="type object">object</a></span> of that class by passing the class name instead of an <span class="type"><a href="language.types.object.html" class="type object">object</a></span> at index 0. As of PHP 5.2.3, it is also possible to pass <em>'ClassName::methodName'</em>. </p> <p class="para"> Apart from common user-defined function, <a href="functions.anonymous.html" class="link">anonymous functions</a> can also be passed to a callback parameter. </p> <p class="para"> <div class="example" id="example-97"> <p><strong>Example #1 Callback function examples </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php <br /><br /></span><span style="color: #FF8000">// An example callback function<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">my_callback_function</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">'hello world!'</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// An example callback method<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">MyClass </span><span style="color: #007700">{<br /> static function </span><span style="color: #0000BB">myCallbackMethod</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">'Hello World!'</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #FF8000">// Type 1: Simple callback<br /></span><span style="color: #0000BB">call_user_func</span><span style="color: #007700">(</span><span style="color: #DD0000">'my_callback_function'</span><span style="color: #007700">); <br /><br /></span><span style="color: #FF8000">// Type 2: Static class method call<br /></span><span style="color: #0000BB">call_user_func</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'MyClass'</span><span style="color: #007700">, </span><span style="color: #DD0000">'myCallbackMethod'</span><span style="color: #007700">)); <br /><br /></span><span style="color: #FF8000">// Type 3: Object method call<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">MyClass</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">call_user_func</span><span style="color: #007700">(array(</span><span style="color: #0000BB">$obj</span><span style="color: #007700">, </span><span style="color: #DD0000">'myCallbackMethod'</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">// Type 4: Static class method call (As of PHP 5.2.3)<br /></span><span style="color: #0000BB">call_user_func</span><span style="color: #007700">(</span><span style="color: #DD0000">'MyClass::myCallbackMethod'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Type 5: Relative static class method call (As of PHP 5.3.0)<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">A </span><span style="color: #007700">{<br /> public static function </span><span style="color: #0000BB">who</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">"A\n"</span><span style="color: #007700">;<br /> }<br />}<br /><br />class </span><span style="color: #0000BB">B </span><span style="color: #007700">extends </span><span style="color: #0000BB">A </span><span style="color: #007700">{<br /> public static function </span><span style="color: #0000BB">who</span><span style="color: #007700">() {<br /> echo </span><span style="color: #DD0000">"B\n"</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">call_user_func</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'B'</span><span style="color: #007700">, </span><span style="color: #DD0000">'parent::who'</span><span style="color: #007700">)); </span><span style="color: #FF8000">// A<br /></span><span style="color: #0000BB">?></span> </span> </code></div> </div> </div> </p> <p class="para"> <div class="example" id="example-98"> <p><strong>Example #2 Callback example using a Closure </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"> <span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// Our closure<br /></span><span style="color: #0000BB">$double </span><span style="color: #007700">= function(</span><span style="color: #0000BB">$a</span><span style="color: #007700">) {<br /> return </span><span style="color: #0000BB">$a </span><span style="color: #007700">* </span><span style="color: #0000BB">2</span><span style="color: #007700">;<br />};<br /><br /></span><span style="color: #FF8000">// This is our range of numbers<br /></span><span style="color: #0000BB">$numbers </span><span style="color: #007700">= </span><span style="color: #0000BB">range</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">5</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Use the closure as a callback here to <br />// double the size of each element in our <br />// range<br /></span><span style="color: #0000BB">$new_numbers </span><span style="color: #007700">= </span><span style="color: #0000BB">array_map</span><span style="color: #007700">(</span><span style="color: #0000BB">$double</span><span style="color: #007700">, </span><span style="color: #0000BB">$numbers</span><span style="color: #007700">);<br /><br />print </span><span style="color: #0000BB">implode</span><span style="color: #007700">(</span><span style="color: #DD0000">' '</span><span style="color: #007700">, </span><span style="color: #0000BB">$new_numbers</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> 2 4 6 8 10 </pre></div> </div> </div> </p> <blockquote class="note"><p><strong class="note">Note</strong>: <span class="simpara"> In PHP 4, it was necessary to use a reference to create a callback that points to the actual <span class="type"><a href="language.types.object.html" class="type object">object</a></span>, and not a copy of it. For more details, see <a href="language.references.html" class="link">References Explained</a>. </span> </p></blockquote> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para">Callbacks registered with functions such as <span class="function"><a href="function.call-user-func.html" class="function">call_user_func()</a></span> and <span class="function"><a href="function.call-user-func-array.html" class="function">call_user_func_array()</a></span> will not be called if there is an uncaught exception thrown in a previous callback.</p></p></blockquote> </div> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="language.types.null.html">NULL</a></div> <div class="next" style="text-align: right; float: right;"><a href="language.pseudo-types.html">Pseudo-types and variables used in this documentation</a></div> <div class="up"><a href="language.types.html">Types</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>