php-doc-en/language/oop5/overloading.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
 <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>.
   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.
   Method __isset is called also with <function>empty</function>.
  </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);

    public 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";
        }
    }

    public 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";
        }
    }

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

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

    public 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>
    The magic method __call() allows to capture invocation of non existing 
    methods. That way __call() can be used to implement user defined method 
    handling that depends on the name of the actual method being called. This 
    is for instance useful for proxy implementations. 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);

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