php-doc-en/language/oop5/magic.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.20 $ -->
 <sect1 xml:id="language.oop5.magic" xmlns="http://docbook.org/ns/docbook">
  <title>Magic Methods</title>
  <para>
   The function names
   <literal>__construct</literal>,
   <literal>__destruct</literal>
   (see <link linkend="language.oop5.decon">Constructors and Destructors</link>),
   <literal>__call</literal>,
   <literal>__callStatic</literal>,
   <literal>__get</literal>,
   <literal>__set</literal>,
   <literal>__isset</literal>,
   <literal>__unset</literal>   
   (see <link linkend="language.oop5.overloading">Overloading</link>),
   <literal>__sleep</literal>,
   <literal>__wakeup</literal>,
   <literal>__toString</literal>,
   <literal>__set_state</literal> and
   <link linkend="language.oop5.cloning">__clone</link>   
   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.
  </para>

  <caution>
   <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.
   </simpara>
  </caution>
 
  <sect2 xml:id="language.oop5.magic.sleep">
   <title><literal>__sleep</literal> and <literal>__wakeup</literal></title>
   <para>
    <function>serialize</function> checks if your class has a function with
    the magic name <literal>__sleep</literal>. 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 &null; is serialized and
    E_NOTICE is issued.
   </para>
   <para>
    The intended use of <literal>__sleep</literal> 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.
   </para>
   <para>
    Conversely, <function>unserialize</function> checks for the
    presence of a function with the magic name 
    <literal>__wakeup</literal>. If present, this function can
    reconstruct any resources that the object may have.
   </para>
   <para>
    The intended use of <literal>__wakeup</literal> is to
    reestablish any database connections that may have been lost
    during serialization and perform other reinitialization
    tasks.
   </para>
   <example>
    <title>Sleep and wakeup</title>
    <programlisting role="php">
<![CDATA[
<?php
class Connection {
    protected $link;
    private $server, $username, $password, $db;
    
    public function __construct($server, $username, $password, $db)
    {
        $this->server = $server;
        $this->username = $username;
        $this->password = $password;
        $this->db = $db;
        $this->connect();
    }
    
    private function connect()
    {
        $this->link = mysql_connect($this->server, $this->username, $this->password);
        mysql_select_db($this->db, $this->link);
    }
    
    public function __sleep()
    {
        return array('server', 'username', 'password', 'db');
    }
    
    public function __wakeup()
    {
        $this->connect();
    }
}
?>
]]>
    </programlisting>
   </example>
  </sect2>

  <sect2 xml:id="language.oop5.magic.tostring">
   <title><literal>__toString</literal></title>
   <para>
    The <literal>__toString</literal> method allows a class to decide
    how it will react when it is converted to a string.
   </para>
   <example>
    <title>Simple example</title>
    <programlisting role="php">
<![CDATA[
<?php
// Declare a simple class
class TestClass
{
    public $foo;

    public function __construct($foo) {
        $this->foo = $foo;
    }

    public function __toString() {
        return $this->foo;
    }
}

$class = new TestClass('Hello');
echo $class;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Hello
]]>
    </screen>
   </example>
   <para>
    It is worth noting that before PHP 5.2.0 the <literal>__toString</literal>
    method was only called when it was directly combined with
    <function>echo</function> or <function>print</function>.
    Since PHP 5.2.0, it is called in any string context (e.g. in
    <function>printf</function> with <literal>%s</literal> modifier) but not
    in other types contexts (e.g. with <literal>%d</literal> modifier).
    Since PHP 5.2.0, converting objects without <literal>__toString</literal>
    method to string would cause <constant>E_RECOVERABLE_ERROR</constant>.
   </para>
  </sect2>

  <sect2 xml:id="language.oop5.magic.set-state">
   <title><literal>__set_state</literal></title>
   <para>
    This <link linkend="language.oop5.static">static</link> method is called
    for classes exported by <function>var_export</function> since PHP 5.1.0.
   </para>
   <para>
    The only parameter of this method is an array containing exported
    properties in the form <literal>array('property' => value, ...)</literal>.
   </para>
   <example>
    <title>Using <literal>__set_state</literal> (since PHP 5.1.0)</title>
    <programlisting role="php">
<![CDATA[
<?php

class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array) // As of PHP 5.1.0
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        $obj->var2 = $an_array['var2'];
        return $obj;
    }
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
                                            //    'var1' => 5,
                                            //    'var2' => 'foo',
                                            // ));
var_dump($b);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}
]]>
    </screen>
   </example>
  </sect2>
 </sect1>
 
<!-- 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:"../../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
-->