Adding documentation for the new experimental overload extension

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@61843 c90b9560-bf6c-de11-be94-00142212c4b1

functions/overload.xml

@@ -0,0 +1,140 @@
+<?xml encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+ <reference id="ref.overload">
+  <title>Object property and method call overloading</title>
+  <titleabbrev>Object overloading</titleabbrev>
+
+  <partintro id="overload.partintro">
+   &warn.experimental;
+   <para>
+    The purpose of this extension is to allow overloading of object
+    property access and method calls. Only one function is defined
+    in this extension, <function>overload</function> which
+    takes the name of the class that should have this functionality
+    enabled. The class named has to define appropriate methods if
+    it wants to have this functionality: <literal>__get()</literal>,
+    <literal>__set()</literal> and <literal>__call()</literal>
+    respectively for getting/setting a property, or calling a method.
+    This way overloading can be selective. Inside these handler
+    functions the overloading is disabled so you can access object
+    properties normally.
+   </para>
+   <para>
+    Some simple examples on using the <function>overload</function>
+    function:
+    <example>
+     <title>Overloading a PHP class</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+
+class OO
+{
+    var $a = 111;
+    var $elem = array('b' => 9, 'c' => 42);
+
+    // Callback method for getting a property
+    function __get($prop_name, &$prop_value)
+    {
+        if (isset($this->elem[$prop_name])) {
+            $prop_value = $this->elem[$prop_name];
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    // Callback method for setting a property
+    function __set($prop_name, $prop_value)
+    {
+        $this->elem[$prop_name] = $prop_value;
+        return true;
+    }
+}
+
+// Here we overload the OO object
+overload('OO');
+
+$o = new OO;
+print "\$o->a: $o->a\n"; // print: $o->a:
+print "\$o->b: $o->b\n"; // print: $o->b: 9
+print "\$o->c: $o->c\n"; // print: $o->c: 42
+print "\$o->d: $o->d\n"; // print: $o->d:
+
+// add a new item to the $elem array in OO
+$o->x = 56; 
+
+// instantiate stdclass (it is built-in in PHP 4)
+$val = new stdclass;
+$val->prop = 555;
+
+// Set "a" to be an array with the $val object in it
+// But __set() will put this in the $elem array
+$o->a = array($val);
+var_dump($o->a[0]->prop);
+
+?>
+]]>
+     </programlisting>
+    </example>
+   </para>
+   <para>
+    As this is an experimental extension, not all things
+    work. There is no <literal>__call()</literal> support
+    currently, you can only overload the get and set
+    operations for properties. You cannot invoke the
+    original overloading handlers of the class, and
+    <literal>__set()</literal> only works to one level
+    of property access.
+   </para>
+  </partintro>
+
+  <refentry id="function.overload">
+   <refnamediv>
+    <refname>overload</refname>
+    <refpurpose>Enable property and method call overloading for a class</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <funcsynopsis>
+     <funcprototype>
+      <funcdef>void
+       <function>overload</function>
+      </funcdef>
+      <paramdef>string 
+       <parameter>
+        <optional>class_name</optional>
+       </parameter>
+      </paramdef>
+     </funcprototype>
+    </funcsynopsis>
+    <para>
+     The <function>overload</function> function will enable
+     property and method call overloading for a class identified
+     by <parameter>class_name</parameter>.
+     <link linkend="overload.partintro">See an example
+     in the introductory section of this part</link>.
+    </para>
+   </refsect1>
+  </refentry>
+ </reference>
+
+<!-- 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
+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
+-->