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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.25 $ -->
 <sect1 xml:id="language.oop5.overloading" xmlns="http://docbook.org/ns/docbook">
  <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
   <modifier>public</modifier> member or method you're trying to access.
   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>
  <para>
   PHP 5.3.0 added the ability to overload
   <link linkend="language.oop5.static">static</link> methods via __callStatic.
  </para>

  <sect2 xml: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>

   <note>
    <para>
     The <literal>__set()</literal> method cannot take arguments by reference.
    </para>
   </note>

   <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":"Setter":private]=>
  array(2) {
    ["b"]=>
    int(2)
    ["c"]=>
    int(3)
  }
}
]]>
    </screen>

   </example>
  </sect2>

  <sect2 xml: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>
   <methodsynopsis>
    <type>mixed</type><methodname>__callStatic</methodname>
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
    <methodparam><type>array</type><parameter>arguments</parameter></methodparam>
   </methodsynopsis>

   <para>
    The magic methods __call() and __callStatic()
    allow capturing invocation of non existent methods.
    These methods 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 these
    methods will be returned to the caller of the method.
   </para>


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

    public function __call($m, $a)
    {
        print "Instantiated method '$m' called:\n";
        var_dump($a);
        return $this->x;
    }
}

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

Instantiated method 'test' called:
array(2) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
}
array(2) {
  [0]=>
  int(10)
  [1]=>
  int(20)
}
]]>
    </screen>
   </example>

   <example>
    <title>overloading instantiated methods with __call</title>
    <programlisting role="php">
  <![CDATA[
<?php
class Caller
{
    private static $x = array(10, 20);

    public static function __callStatic($m, $a)
    {
        print "Static method '$m' called:\n";
        var_dump($a);
        return self::$x;
    }
}

$a = Caller::test('a', 'b');
var_dump($a);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[

Static method 'test' called:
array(2) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
}
array(2) {
  [0]=>
  int(10)
  [1]=>
  int(20)
}
]]>
    </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
-->