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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
 <sect1 id="language.oop5.magic">
  <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>__get</literal>,
   <literal>__set</literal>
   (see <link linkend="language.oop5.overloading">Overloading</link>),
   <literal>__sleep</literal>,
   <literal>__wakeup</literal>, and
   <literal>__toString</literal> 
   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 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.
   </para>
   <para>
    The intended use of <literal>__sleep</literal> is to close any
    database connections that the object may have, 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>
  </sect2>

  <sect2 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 the <literal>__toString</literal> method
    will only be called when it is directly combined with
    <function>echo</function> or <function>print</function>.
   </para>
   <example>
    <title>Cases where <literal>__toString</literal> is called</title>
    <programlisting role="php">
<![CDATA[
<?php
// __toString called
echo $class;

// __toString called (still a normal parameter for echo)
echo 'text', $class;

// __toString not called (concatenation operator used first)
echo 'text' . $class;

// __toString not called (cast to string first)
echo (string) $class;

// __toString not called (cast to string first)
echo "text $class";
?>
]]>
    </programlisting>
   </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
-->