<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
 <sect1 id="language.oop5.overloading">
  <title>Overloading</title>

  <para>
   Both method calls and member accesses can be overloaded via the
   __call, __get and __set methods. These methods will only be
   triggered when your object or inherited object doesn't contain the 
   member or method you're trying to access.
   All overloading methods must not be defined as
   <link linkend="language.oop5.static">static</link>.
   In PHP 5.0.x, all overloading methods must be defined as
   <link linkend="language.oop5.visibility">public</link>.
  </para>
  <para>
   Since PHP 5.1.0 it is also possible to overload the
   <function>isset</function> and <function>unset</function> functions via the
   __isset and __unset methods respectively.
  </para>

  <sect2 id="language.oop5.overloading.members">
   <title>Member overloading</title>

   <methodsynopsis>
    <type>void</type><methodname>__set</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
    <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
   </methodsynopsis>
   <methodsynopsis>
    <type>mixed</type><methodname>__get</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <methodsynopsis>
    <type>bool</type><methodname>__isset</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <methodsynopsis>
    <type>void</type><methodname>__unset</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>

   <para>
    Class members can be overloaded to run custom code defined in your class
    by defining these specially named methods. The <varname>$name</varname> 
    parameter used is the name of the variable that should be set or retrieved.
    The __set() method's <varname>$value</varname> parameter specifies the 
    value that the object should set the <varname>$name</varname>.
   </para>

   <example>
    <title>overloading with __get, __set, __isset and __unset example</title>
    <programlisting role="php">
<![CDATA[
<?php
class Setter
{
    public $n;
    private $x = array("a" => 1, "b" => 2, "c" => 3);

    private function __get($nm)
    {
        echo "Getting [$nm]\n";

        if (isset($this->x[$nm])) {
            $r = $this->x[$nm];
            print "Returning: $r\n";
            return $r;
        } else {
            echo "Nothing!\n";
        }
    }

    private function __set($nm, $val)
    {
        echo "Setting [$nm] to $val\n";

        if (isset($this->x[$nm])) {
            $this->x[$nm] = $val;
            echo "OK!\n";
        } else {
            echo "Not OK!\n";
        }
    }

    private function __isset($nm)
    {
        echo "Checking if $nm is set\n";

        return isset($this->x[$nm]);
    }

    private function __unset($nm)
    {
        echo "Unsetting $nm\n";

        unset($this->x[$nm]);
    }
}

$foo = new Setter();
$foo->n = 1;
$foo->a = 100;
$foo->a++;
$foo->z++;

var_dump(isset($foo->a)); //true
unset($foo->a);
var_dump(isset($foo->a)); //false

// this doesn't pass through the __isset() method
// because 'n' is a public property
var_dump(isset($foo->n));

var_dump($foo);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Setting [a] to 100
OK!
Getting [a]
Returning: 100
Setting [a] to 101
OK!
Getting [z]
Nothing!
Setting [z] to 1
Not OK!

Checking if a is set
bool(true)
Unsetting a
Checking if a is set
bool(false)
bool(true)

object(Setter)#1 (2) {
  ["n"]=>
  int(1)
  ["x:private"]=>
  array(2) {
    ["b"]=>
    int(2)
    ["c"]=>
    int(3)
  }
}
]]>
    </screen>

   </example>
  </sect2>

  <sect2 id="language.oop5.overloading.methods">
   <title>Method overloading</title>

   <methodsynopsis>
    <type>mixed</type><methodname>__call</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
    <methodparam><type>array</type><parameter>arguments</parameter></methodparam>
   </methodsynopsis>

   <para>
    Class methods can be overloaded to run custom code defined in your class
    by defining this specially named method. The <varname>$name</varname> 
    parameter used is the name as the function name that was requested 
    to be used. The arguments that were passed in the function will be 
    defined as an array in the <varname>$arguments</varname> parameter.
    The value returned from the __call() method will be returned to the
    caller of the method.
   </para>

   <example>
    <title>overloading with __call example</title>
    <programlisting role="php">
  <![CDATA[
<?php
class Caller
{
    private $x = array(1, 2, 3);

    private function __call($m, $a)
    {
        print "Method $m called:\n";
        var_dump($a);
        return $this->x;
    }
}

$foo = new Caller();
$a = $foo->test(1, "2", 3.4, true);
var_dump($a);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[

Method test called:
array(4) {
    [0]=>
    int(1)
    [1]=>
    string(1) "2"
    [2]=>
    float(3.4)
    [3]=>
    bool(true)
}
array(3) {
    [0]=>
    int(1)
    [1]=>
    int(2)
    [2]=>
    int(3)
}
]]>
    </screen>
   </example>

  </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
-->