aidan Wed Sep 29 12:27:24 2004 EDT
Modified files:
/phpdoc/en/language/oop5 magic.xml
Log:
Document the magic methods
http://cvs.php.net/diff.php/phpdoc/en/language/oop5/magic.xml?r1=1.1&r2=1.2&ty=u
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
