cvs: phpdoc /en/language/oop5 magic.xml

aidan		Wed Sep 29 12:27:24 2004 EDT

Modified files:
/phpdoc/en/language/oop5	magic.xml
Log:
Document the magic methods

[url]http://cvs.php.net/diff.php/phpdoc/en/language/oop5/magic.xml?r1=1.1&r2=1.2&ty=u[/
url]
Index: phpdoc/en/language/oop5/magic.xml
diff -u phpdoc/en/language/oop5/magic.xml:1.1 phpdoc/en/language/oop5/magic.
xml:1.2
--- phpdoc/en/language/oop5/magic.xml:1.1	Sun Jul 11 08:33:25 2004
+++ phpdoc/en/language/oop5/magic.xml	Wed Sep 29 12:27:24 2004
@@ -1,12 +1,90 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<sect1 id="language.oop5.magic">
<title>Magic Methods</title>
<para>
-   .
+   The function names
+   <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