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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
 <sect1 id="language.oop5.magic">
  <title>Magic Methods</title>
  <para>
   The function names
   <literal>__construct</literal>,
   <literal>__destruct</literal>,
   <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
    being run 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 object may have, committing pending
    data or perform similar cleanup tasks. Also, the function is
    useful if you have very large objects which need not 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 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>
   <programlisting role="php">
<![CDATA[
<?php
// Define 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>
  </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
-->