<!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>Magic Methods</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.oop5.iterations.html">Object Iteration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.oop5.final.html">Final Keyword</a></div>
<div class="up"><a href="language.oop5.html">Classes and Objects</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="language.oop5.magic" class="sect1">
<h2 class="title">Magic Methods</h2>
<p class="para">
The function names
<a href="language.oop5.decon.html#object.construct" class="link">__construct()</a>,
<a href="language.oop5.decon.html#object.destruct" class="link">__destruct()</a>,
<a href="language.oop5.overloading.html#object.call" class="link">__call()</a>,
<a href="language.oop5.overloading.html#object.callstatic" class="link">__callStatic()</a>,
<a href="language.oop5.overloading.html#object.get" class="link">__get()</a>,
<a href="language.oop5.overloading.html#object.set" class="link">__set()</a>,
<a href="language.oop5.overloading.html#object.isset" class="link">__isset()</a>,
<a href="language.oop5.overloading.html#object.unset" class="link">__unset()</a>,
<a href="language.oop5.magic.html#object.sleep" class="link">__sleep()</a>,
<a href="language.oop5.magic.html#object.wakeup" class="link">__wakeup()</a>,
<a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a>,
<a href="language.oop5.magic.html#object.invoke" class="link">__invoke()</a>,
<a href="language.oop5.magic.html#object.set-state" class="link">__set_state()</a> and
<a href="language.oop5.cloning.html#object.clone" class="link">__clone()</a>
are magical in PHP classes. You
cannot have functions with these names in any of your
classes unless you want the magic functionality associated
with them.
</p>
<div class="caution"><strong class="caution">Caution</strong>
<p class="simpara">
PHP reserves all function names starting with __ as magical.
It is recommended that you do not use function names with
__ in PHP unless you want some documented magic functionality.
</p>
</div>
<div class="sect2" id="language.oop5.magic.sleep">
<h3 class="title">
<a href="language.oop5.magic.html#object.sleep" class="link">__sleep()</a> and
<a href="language.oop5.magic.html#object.wakeup" class="link">__wakeup()</a>
</h3>
<div class="methodsynopsis dc-description" id="object.sleep">
<span class="modifier">public</span> <span class="type">array</span> <span class="methodname"><strong>__sleep</strong></span>
( <span class="methodparam">void</span>
)</div>
<div class="methodsynopsis dc-description" id="object.wakeup">
<span class="type"><span class="type void">void</span></span> <span class="methodname"><strong>__wakeup</strong></span>
( <span class="methodparam">void</span>
)</div>
<p class="para">
<span class="function"><a href="function.serialize.html" class="function">serialize()</a></span> checks if your class has a function with
the magic name <a href="language.oop5.magic.html#object.sleep" class="link">__sleep()</a>. If so, that function is
executed prior to any serialization. It can clean up the object
and is supposed to return an array with the names of all variables
of that object that should be serialized.
If the method doesn't return anything then <strong><code>NULL</code></strong> is serialized and
<strong><code>E_NOTICE</code></strong> is issued.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
It is not possible for <a href="language.oop5.magic.html#object.sleep" class="link">__sleep()</a> to return names of
private properties in parent classes. Doing this will result in an
<strong><code>E_NOTICE</code></strong> level error. Instead you may use the
<a href="class.serializable.html" class="classname">Serializable</a> interface.
</p>
</p></blockquote>
<p class="para">
The intended use of <a href="language.oop5.magic.html#object.sleep" class="link">__sleep()</a> is to commit pending
data or perform similar cleanup tasks. Also, the function is
useful if you have very large objects which do not need to be
saved completely.
</p>
<p class="para">
Conversely, <span class="function"><a href="function.unserialize.html" class="function">unserialize()</a></span> checks for the
presence of a function with the magic name
<a href="language.oop5.magic.html#object.wakeup" class="link">__wakeup()</a>. If present, this function can
reconstruct any resources that the object may have.
</p>
<p class="para">
The intended use of <a href="language.oop5.magic.html#object.wakeup" class="link">__wakeup()</a> is to
reestablish any database connections that may have been lost
during serialization and perform other reinitialization
tasks.
</p>
<div class="example" id="example-219">
<p><strong>Example #1 Sleep and wakeup</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">Connection<br /></span><span style="color: #007700">{<br /> protected </span><span style="color: #0000BB">$link</span><span style="color: #007700">;<br /> private </span><span style="color: #0000BB">$dsn</span><span style="color: #007700">, </span><span style="color: #0000BB">$username</span><span style="color: #007700">, </span><span style="color: #0000BB">$password</span><span style="color: #007700">;<br /> <br /> public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$dsn</span><span style="color: #007700">, </span><span style="color: #0000BB">$username</span><span style="color: #007700">, </span><span style="color: #0000BB">$password</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">dsn </span><span style="color: #007700">= </span><span style="color: #0000BB">$dsn</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">username </span><span style="color: #007700">= </span><span style="color: #0000BB">$username</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">password </span><span style="color: #007700">= </span><span style="color: #0000BB">$password</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">connect</span><span style="color: #007700">();<br /> }<br /> <br /> private function </span><span style="color: #0000BB">connect</span><span style="color: #007700">()<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">link </span><span style="color: #007700">= new </span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">dsn</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">username</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">password</span><span style="color: #007700">);<br /> }<br /> <br /> public function </span><span style="color: #0000BB">__sleep</span><span style="color: #007700">()<br /> {<br /> return array(</span><span style="color: #DD0000">'dsn'</span><span style="color: #007700">, </span><span style="color: #DD0000">'username'</span><span style="color: #007700">, </span><span style="color: #DD0000">'password'</span><span style="color: #007700">);<br /> }<br /> <br /> public function </span><span style="color: #0000BB">__wakeup</span><span style="color: #007700">()<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">connect</span><span style="color: #007700">();<br /> }<br />}</span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="sect2" id="language.oop5.magic.tostring">
<h3 class="title"><a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a></h3>
<div class="methodsynopsis dc-description" id="object.tostring">
<span class="modifier">public</span> <span class="type">string</span> <span class="methodname"><strong>__toString</strong></span>
( <span class="methodparam">void</span>
)</div>
<p class="para">
The <a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a> method allows a class to decide
how it will react when it is treated like a string. For example,
what <em>echo $obj;</em> will print. This method must
return a string, as otherwise a fatal <strong><code>E_RECOVERABLE_ERROR</code></strong>
level error is emitted.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="simpara">
You cannot throw an exception from within a
<a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a> method. Doing so will
result in a fatal error.
</p>
</div>
<div class="example" id="example-220">
<p><strong>Example #2 Simple example</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">// Declare a simple class<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">TestClass<br /></span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$foo</span><span style="color: #007700">;<br /><br /> public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$foo</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">foo </span><span style="color: #007700">= </span><span style="color: #0000BB">$foo</span><span style="color: #007700">;<br /> }<br /><br /> public function </span><span style="color: #0000BB">__toString</span><span style="color: #007700">()<br /> {<br /> return </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">foo</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$class </span><span style="color: #007700">= new </span><span style="color: #0000BB">TestClass</span><span style="color: #007700">(</span><span style="color: #DD0000">'Hello'</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$class</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>
Hello
</pre></div>
</div>
</div>
<p class="para">
It is worth noting that before PHP 5.2.0 the <a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a>
method was only called when it was directly combined with
<span class="function"><a href="function.echo.html" class="function">echo</a></span> or <span class="function"><a href="function.print.html" class="function">print</a></span>.
Since PHP 5.2.0, it is called in any string context (e.g. in
<span class="function"><a href="function.printf.html" class="function">printf()</a></span> with <em>%s</em> modifier) but not
in other types contexts (e.g. with <em>%d</em> modifier).
Since PHP 5.2.0, converting objects without <a href="language.oop5.magic.html#object.tostring" class="link">__toString()</a>
method to string would cause <strong><code>E_RECOVERABLE_ERROR</code></strong>.
</p>
</div>
<div class="sect2" id="language.oop5.magic.invoke">
<h3 class="title"><a href="language.oop5.magic.html#object.invoke" class="link">__invoke()</a></h3>
<div class="methodsynopsis dc-description" id="object.invoke">
<span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><strong>__invoke</strong></span>
([ <span class="methodparam"> <code class="parameter">$...</code></span>
] )</div>
<p class="para">
The <a href="language.oop5.magic.html#object.invoke" class="link">__invoke()</a> method is called when a script tries to
call an object as a function.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
This feature is available since PHP 5.3.0.
</p>
</p></blockquote>
<div class="example" id="example-221">
<p><strong>Example #3 Using <a href="language.oop5.magic.html#object.invoke" class="link">__invoke()</a></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">CallableClass<br /></span><span style="color: #007700">{<br /> public function </span><span style="color: #0000BB">__invoke</span><span style="color: #007700">(</span><span style="color: #0000BB">$x</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$x</span><span style="color: #007700">);<br /> }<br />}<br /></span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">CallableClass</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$obj</span><span style="color: #007700">(</span><span style="color: #0000BB">5</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">is_callable</span><span style="color: #007700">(</span><span style="color: #0000BB">$obj</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>
int(5)
bool(true)
</pre></div>
</div>
</div>
</div>
<div class="sect2" id="language.oop5.magic.set-state">
<h3 class="title"><a href="language.oop5.magic.html#object.set-state" class="link">__set_state()</a></h3>
<div class="methodsynopsis dc-description" id="object.set-state">
<span class="modifier">static</span> <span class="type">object</span> <span class="methodname"><strong>__set_state</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$properties</code></span>
)</div>
<p class="para">
This <a href="language.oop5.static.html" class="link">static</a> method is called
for classes exported by <span class="function"><a href="function.var-export.html" class="function">var_export()</a></span> since PHP 5.1.0.
</p>
<p class="para">
The only parameter of this method is an array containing exported
properties in the form <em>array('property' => value, ...)</em>.
</p>
<div class="example" id="example-222">
<p><strong>Example #4 Using <a href="language.oop5.magic.html#object.set-state" class="link">__set_state()</a> (since PHP 5.1.0)</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: #007700">class </span><span style="color: #0000BB">A<br /></span><span style="color: #007700">{<br /> public </span><span style="color: #0000BB">$var1</span><span style="color: #007700">;<br /> public </span><span style="color: #0000BB">$var2</span><span style="color: #007700">;<br /><br /> public static function </span><span style="color: #0000BB">__set_state</span><span style="color: #007700">(</span><span style="color: #0000BB">$an_array</span><span style="color: #007700">) </span><span style="color: #FF8000">// As of PHP 5.1.0<br /> </span><span style="color: #007700">{<br /> </span><span style="color: #0000BB">$obj </span><span style="color: #007700">= new </span><span style="color: #0000BB">A</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$obj</span><span style="color: #007700">-></span><span style="color: #0000BB">var1 </span><span style="color: #007700">= </span><span style="color: #0000BB">$an_array</span><span style="color: #007700">[</span><span style="color: #DD0000">'var1'</span><span style="color: #007700">];<br /> </span><span style="color: #0000BB">$obj</span><span style="color: #007700">-></span><span style="color: #0000BB">var2 </span><span style="color: #007700">= </span><span style="color: #0000BB">$an_array</span><span style="color: #007700">[</span><span style="color: #DD0000">'var2'</span><span style="color: #007700">];<br /> return </span><span style="color: #0000BB">$obj</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= new </span><span style="color: #0000BB">A</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">-></span><span style="color: #0000BB">var1 </span><span style="color: #007700">= </span><span style="color: #0000BB">5</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$a</span><span style="color: #007700">-></span><span style="color: #0000BB">var2 </span><span style="color: #007700">= </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">;<br /><br />eval(</span><span style="color: #DD0000">'$b = ' </span><span style="color: #007700">. </span><span style="color: #0000BB">var_export</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">true</span><span style="color: #007700">) . </span><span style="color: #DD0000">';'</span><span style="color: #007700">); </span><span style="color: #FF8000">// $b = A::__set_state(array(<br /> // 'var1' => 5,<br /> // 'var2' => 'foo',<br /> // ));<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$b</span><span style="color: #007700">);<br /><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>
object(A)#2 (2) {
["var1"]=>
int(5)
["var2"]=>
string(3) "foo"
}
</pre></div>
</div>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="language.oop5.iterations.html">Object Iteration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="language.oop5.final.html">Final Keyword</a></div>
<div class="up"><a href="language.oop5.html">Classes and Objects</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
