goba Sat Nov 10 12:43:04 2001 EDT
Added files:
/phpdoc/en/functions overload.xml
Log:
Adding documentation for the new experimental overload extension
Index: phpdoc/en/functions/overload.xml
+++ phpdoc/en/functions/overload.xml
<?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
-->
