magic.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 8f51247cb4631b29686f867bd904dfe5b2678074 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<sect1 xml:id="language.oop5.magic" xmlns="http://docbook.org/ns/docbook">
  <title>Métodos mágicos</title>
  <para>
   Los métodos mágicos son métodos especiales que sobrescriben la acción
   por omisión de PHP cuando se realizan ciertas acciones sobre un objeto.
  </para>
 <caution>
  <simpara>
   Todos los métodos que comienzan por <literal>__</literal> están reservados por PHP.
   Por lo tanto, no se recomienda utilizar un nombre de método de este tipo, excepto cuando
   se sobrescribe el comportamiento de PHP.
  </simpara>
 </caution>
 <para>
  Los siguientes métodos se consideran mágicos:
  <!-- Should be an itemized list ? -->
  <link linkend="object.construct">__construct()</link>,
  <link linkend="object.destruct">__destruct()</link>,
  <link linkend="object.call">__call()</link>,
  <link linkend="object.callstatic">__callStatic()</link>,
  <link linkend="object.get">__get()</link>,
  <link linkend="object.set">__set()</link>,
  <link linkend="object.isset">__isset()</link>,
  <link linkend="object.unset">__unset()</link>,
  <link linkend="object.serialize">__serialize()</link>,
  <link linkend="object.unserialize">__unserialize()</link>,
  <link linkend="object.sleep">__sleep()</link>,
  <link linkend="object.wakeup">__wakeup()</link>,
  <link linkend="object.tostring">__toString()</link>,
  <link linkend="object.invoke">__invoke()</link>,
  <link linkend="object.set-state">__set_state()</link>
  <link linkend="object.clone">__clone()</link>, y
  <link linkend="object.debuginfo">__debugInfo()</link>.
 </para>

  <warning>
   <simpara>
    Todos los métodos mágicos, excepto
    <link linkend="object.construct">__construct()</link>,
    <link linkend="object.destruct">__destruct()</link>, y
    <link linkend="object.clone">__clone()</link>,
    <emphasis>deben</emphasis> ser declarados como <literal>public</literal>,
    de lo contrario se emitirá una <constant>E_WARNING</constant>.
    Anterior a PHP 8.0.0, no se emitía ningún diagnóstico para los métodos mágicos
    <link linkend="object.sleep">__sleep()</link>,
    <link linkend="object.wakeup">__wakeup()</link>,
    <link linkend="object.serialize">__serialize()</link>,
    <link linkend="object.unserialize">__unserialize()</link>, y
    <link linkend="object.set-state">__set_state()</link>.
   </simpara>
  </warning>
 <warning>
  <para>
   Si se utilizan declaraciones de tipos en la definición de un método
   mágico, deben ser idénticas a la firma descrita en este documento.
   De lo contrario, se emitirá un error fatal.
   Anterior a PHP 8.0.0, no se emitía ningún diagnóstico.
   Sin embargo, <link linkend="object.construct">__construct()</link> y
   <link linkend="object.destruct">__destruct()</link> no deben declarar
   un tipo de retorno; de lo contrario, se emitirá un error fatal.
  </para>
 </warning>

  <sect2 xml:id="language.oop5.magic.serialize">
   <title>
    <link linkend="object.serialize">__serialize()</link> y
    <link linkend="object.unserialize">__unserialize()</link>
   </title>

   <methodsynopsis xml:id="object.serialize">
    <modifier>public</modifier> <type>array</type><methodname>__serialize</methodname>
    <void/>
   </methodsynopsis>
   <methodsynopsis xml:id="object.unserialize">
    <modifier>public</modifier> <type>void</type><methodname>__unserialize</methodname>
    <methodparam><type>array</type><parameter>data</parameter></methodparam>
   </methodsynopsis>

   <para>
    <function>serialize</function> verifica si la clase tiene un método con el
    nombre mágico <link linkend="object.serialize">__serialize()</link>.
    Si es así, este método será ejecutado antes de cualquier serialización.
    Debe construir y devolver un array asociativo de pares clave/valor
    que represente la forma serializada del objeto. Si no se devuelve ningún array, se lanzará una <classname>TypeError</classname>.
   </para>
   <note>
    <para>
     Si <link linkend="object.serialize">__serialize()</link> y
     <link linkend="object.sleep">__sleep()</link> están ambas definidas
     en el mismo objeto, entonces solo <link linkend="object.serialize">__serialize()</link>
     será llamada.
     <link linkend="object.sleep">__sleep()</link> será ignorada. Si el objeto
     implementa la interfaz <link linkend="class.serializable">Serializable</link>,
     el método <literal>serialize()</literal> de la interfaz será ignorado y
     <link linkend="object.serialize">__serialize()</link> será utilizada en su lugar.
    </para>
   </note>
   <para>
    El uso previsto de <link linkend="object.serialize">__serialize()</link>
    es definir una representación arbitraria del objeto para serializarlo
    fácilmente. Los elementos del array pueden corresponder a las propiedades
    del objeto, pero esto no es requerido.
   </para>
   <para>
    Inversamente, <function>unserialize</function> verifica la presencia de
    una función con el nombre mágico
    <link linkend="object.unserialize">__unserialize()</link>.
    Si está presente, esta función recibirá el array restaurado devuelto
    por <link linkend="object.serialize">__serialize()</link>. Puede entonces
    restaurar las propiedades del objeto desde este array como sea apropiado.
   </para>
   <note>
    <para>
     Si <link linkend="object.unserialize">__unserialize()</link> y
     <link linkend="object.wakeup">__wakeup()</link> están ambas definidas
     en el mismo objeto, entonces solo <link linkend="object.unserialize">__unserialize()</link>
     será llamada.
     <link linkend="object.wakeup">__wakeup()</link> será ignorada.
    </para>
   </note>
   <note>
    <para>
     Esta funcionalidad está disponible a partir de PHP 7.4.0.
    </para>
   </note>
   <example>
    <title>Serialize y unserialize</title>
    <programlisting role="php">
<![CDATA[
<?php
class Connection
{
    protected $link;
    private $dsn, $username, $password;

    public function __construct($dsn, $username, $password)
    {
        $this->dsn = $dsn;
        $this->username = $username;
        $this->password = $password;
        $this->connect();
    }

    private function connect()
    {
        $this->link = new PDO($this->dsn, $this->username, $this->password);
    }

    public function __serialize(): array
    {
        return [
          'dsn' => $this->dsn,
          'user' => $this->username,
          'pass' => $this->password,
        ];
    }

    public function __unserialize(array $data): void
    {
        $this->dsn = $data['dsn'];
        $this->username = $data['user'];
        $this->password = $data['pass'];

        $this->connect();
    }
}?>
]]>
    </programlisting>
   </example>
  </sect2>

 <sect2 xml:id="language.oop5.magic.sleep">
  <title>
   <link linkend="object.sleep">__sleep()</link> y
   <link linkend="object.wakeup">__wakeup()</link>
  </title>

  <warning>
   <simpara>
    Este mecanismo de serialización está soft-deprecated a partir de PHP 8.5.0.
    Se mantiene por compatibilidad con versiones anteriores.
    Sin embargo, el código nuevo y existente debe migrarse para usar los
    métodos mágicos <link linkend="object.serialize">__serialize()</link> y
    <link linkend="object.unserialize">__unserialize()</link>
    en su lugar.
   </simpara>
  </warning>

  <methodsynopsis xml:id="object.sleep">
   <modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
   <void/>
  </methodsynopsis>
  <methodsynopsis xml:id="object.wakeup">
   <modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
   <void/>
  </methodsynopsis>

  <para>
   <function>serialize</function> verifica si la clase tiene un método con el
   nombre mágico <link linkend="object.sleep">__sleep()</link>.
   Si es así, este método será ejecutado antes de cualquier serialización. Puede
   limpiar el objeto, y se supone que devuelve un array con los nombres de todas
   las variables del objeto que deben ser serializadas.
   Si el método no devuelve nada, entonces &null; será serializado, y se emitirá una alerta de tipo
   <constant>E_NOTICE</constant>.
  </para>
  <note>
   <para>
    No es posible para <link linkend="object.sleep">__sleep()</link> devolver
    nombres de propiedades privadas de las clases padres. Hacerlo
    resultará en un error de nivel <constant>E_NOTICE</constant>.
    Utilice <link linkend="object.serialize">__serialize()</link> en su lugar.
   </para>
  </note>
  <note>
   <para>
    A partir de PHP 8.0.0, devolver un valor que no sea un array desde
    <link linkend="object.sleep">__sleep()</link> emite una advertencia.
    Anteriormente se emitía una notificación.
   </para>
  </note>
  <para>
   El propósito declarado de <link linkend="object.sleep">__sleep()</link> es validar datos pendientes
   o realizar operaciones de limpieza.
   Además, esta función es útil si un objeto muy grande no necesita
   ser guardado en su totalidad.
  </para>
  <para>
   Reciprocamente, la función <function>unserialize</function> verifica
   la presencia de un método cuyo nombre es el nombre mágico
   <link linkend="object.wakeup">__wakeup()</link>. Si está presente, esta función
   puede reconstruir cualquier recurso que el objeto pudiera poseer.
  </para>
  <para>
   El propósito declarado de <link linkend="object.wakeup">__wakeup()</link> es restablecer
   cualquier conexión de base de datos que se haya perdido
   durante la serialización y realizar tareas de reinicialización.
  </para>
  <example>
   <title>Uso de sleep() y wakeup()</title>
   <programlisting role="php">
<![CDATA[
<?php
class Connection
{
    protected $link;
    private $dsn, $username, $password;

    public function __construct($dsn, $username, $password)
    {
        $this->dsn = $dsn;
        $this->username = $username;
        $this->password = $password;
        $this->connect();
    }

    private function connect()
    {
        $this->link = new PDO($this->dsn, $this->username, $this->password);
    }

    public function __sleep()
    {
        return array('dsn', 'username', 'password');
    }

    public function __wakeup()
    {
        $this->connect();
    }
}?>
]]>
   </programlisting>
  </example>
 </sect2>

  <sect2 xml:id="language.oop5.magic.tostring">
   <title><link linkend="object.tostring">__toString()</link></title>
   <methodsynopsis xml:id="object.tostring">
    <modifier>public</modifier> <type>string</type><methodname>__toString</methodname>
    <void/>
   </methodsynopsis>

   <para>
    El método <link linkend="object.tostring">__toString()</link> determina cómo el objeto
    debe reaccionar cuando se trata como una cadena de caracteres.
    Por ejemplo, lo que <literal>echo $obj;</literal> mostrará.
   </para>
   <warning>
    <para>
     A partir de PHP 8.0.0, el valor de retorno sigue las semánticas estándar
     de PHP, lo que significa que el valor será convertido en una <type>string</type>
     si es posible y si el
     <link linkend="language.types.declarations.strict">typing stricte</link>
     está desactivado.
    </para>
    <para>
     Un objeto <interfacename>Stringable</interfacename>
     <emphasis>no</emphasis> será aceptado por una declaración de tipo <type>string</type> si la
     <link linkend="language.types.declarations.strict">declaración de tipo estricta</link> está activada.
     Si se desea tal comportamiento, la declaración de tipo debe aceptar
     tanto <interfacename>Stringable</interfacename> como <type>string</type> a través de un tipo de unión.
    </para>
    <para>
     A partir de PHP 8.0.0, cualquier clase que contenga un método
     <link linkend="object.tostring">__toString()</link> implementa también
     implícitamente la interfaz <interfacename>Stringable</interfacename>,
     y por lo tanto pasará las verificaciones de tipos para esta interfaz.
     Se recomienda implementar explícitamente la interfaz de todos modos.
    </para>
    <para>
     En PHP 7.4, el valor de retorno <emphasis>debe</emphasis> ser una
     <type>string</type>, de lo contrario se lanzará un <classname>Error</classname>.
    </para>
    <para>
     Anterior a PHP 7.4.0, el valor de retorno <emphasis>debe</emphasis>
     ser una <type>string</type>, de lo contrario se emitirá una <constant>E_RECOVERABLE_ERROR</constant>
     fatal.
    </para>
   </warning>
   <warning>
    <simpara>
     Era imposible lanzar una excepción desde el método
     <link linkend="object.tostring">__toString()</link> anterior a PHP 7.4.0.
     Esto resultaría en un error fatal.
    </simpara>
   </warning>
   <example>
    <title>Ejemplo simple</title>
    <programlisting role="php">
<![CDATA[
<?php
// Declaración de una clase simple
class ClasseTest
{
    public $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    public function __toString()
    {
        return $this->foo;
    }
}

$class = new ClasseTest('Bonjour');
echo $class;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Bonjour
]]>
    </screen>
   </example>
  </sect2>

  <sect2 xml:id="language.oop5.magic.invoke">
   <title><link linkend="object.invoke">__invoke()</link></title>
   <methodsynopsis xml:id="object.invoke">
    <type>mixed</type><methodname>__invoke</methodname>
    <methodparam rep="repeat"><parameter>values</parameter></methodparam>
   </methodsynopsis>

   <para>
    El método <link linkend="object.invoke">__invoke()</link> es llamado cuando un script intenta
    llamar a un objeto como una función.
   </para>
   <example>
    <title>Ejemplo con <link linkend="object.invoke">__invoke()</link></title>
    <programlisting role="php">
<![CDATA[
<?php
class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
int(5)
bool(true)
]]>
    </screen>
   </example>
   <example>
    <title>Ejemplo con <link linkend="object.invoke">__invoke()</link></title>
    <programlisting role="php">
<![CDATA[
<?php
class Sort
{
    private $key;

    public function __construct(string $key)
    {
        $this->key = $key;
    }

    public function __invoke(array $a, array $b): int
    {
        return $a[$this->key] <=> $b[$this->key];
    }
}

$customers = [
    ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
    ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
    ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
];

// ordenar los clientes por nombre
usort($customers, new Sort('first_name'));
print_r($customers);

// ordenar los clientes por apellido
usort($customers, new Sort('last_name'));
print_r($customers);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
     <![CDATA[
Array
(
    [0] => Array
        (
            [id] => 3
            [first_name] => Alice
            [last_name] => Gustav
        )

    [1] => Array
        (
            [id] => 2
            [first_name] => Bob
            [last_name] => Filipe
        )

    [2] => Array
        (
            [id] => 1
            [first_name] => John
            [last_name] => Do
        )

)
Array
(
    [0] => Array
        (
            [id] => 1
            [first_name] => John
            [last_name] => Do
        )

    [1] => Array
        (
            [id] => 2
            [first_name] => Bob
            [last_name] => Filipe
        )

    [2] => Array
        (
            [id] => 3
            [first_name] => Alice
            [last_name] => Gustav
        )

)
]]>
    </screen>
   </example>
  </sect2>

  <sect2 xml:id="language.oop5.magic.set-state">
   <title><link linkend="object.set-state">__set_state()</link></title>
   <methodsynopsis xml:id="object.set-state">
    <modifier>static</modifier> <type>object</type><methodname>__set_state</methodname>
    <methodparam><type>array</type><parameter>properties</parameter></methodparam>
   </methodsynopsis>

   <para>
    Este método <link linkend="language.oop5.static">estático</link> es llamado
    para las clases exportadas por la función <function>var_export</function>.
   </para>
   <para>
    El único parámetro de este método es un array que contiene las propiedades
    exportadas en la forma <literal>['property' => value, ...]</literal>.
   </para>
   <example>
    <title>Uso de <link linkend="object.set-state">__set_state()</link></title>
    <programlisting role="php">
<![CDATA[

class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array)
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        $obj->var2 = $an_array['var2'];
        return $obj;
    }
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

$b = var_export($a, true);
var_dump($b);
eval('$c = ' . $b . ';');
var_dump($c);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
string(60) "A::__set_state(array(
   'var1' => 5,
   'var2' => 'foo',
))"
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}
]]>
    </screen>
   </example>
   <note>
    <simpara>
     Al exportar un objeto, <function>var_export</function> no
     verifica si <link linkend="object.set-state">__set_state()</link> está
     implementada por la clase del objeto, por lo que la reimportación de objetos
     resultará en una excepción <classname>Error</classname>,
     si __set_state() no está implementada.
     En particular, esto afecta a ciertas clases internas.
    </simpara>
    <simpara>
     Es responsabilidad del programador verificar que solo los objetos cuya clase implementa __set_state() serán re-importados.
    </simpara>
   </note>
  </sect2>

  <sect2 xml:id="language.oop5.magic.debuginfo">
   <title><link linkend="object.debuginfo">__debugInfo()</link></title>
   <methodsynopsis xml:id="object.debuginfo">
    <type>array</type><methodname>__debugInfo</methodname>
    <void/>
   </methodsynopsis>
   <para>
    Este método es llamado por <function>var_dump</function> al
    procesar un objeto para recuperar las propiedades que
    deben ser mostradas. Si el método no está definido en un objeto,
    entonces todas las propiedades públicas, protegidas y privadas serán
    mostradas.
   </para>
   <example>
    <title>Uso de <link linkend="object.debuginfo">__debugInfo()</link></title>
    <programlisting role="php">
<![CDATA[
<?php
class C {
    private $prop;

    public function __construct($val) {
        $this->prop = $val;
    }

    public function __debugInfo() {
        return [
            'propSquared' => $this->prop ** 2,
        ];
    }
}

var_dump(new C(42));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}
]]>
    </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:"~/.phpdoc/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
-->