archived-doc-es/language/attributes.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0f14761ba340c6e49797706ac3f0cf1147d97253 Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
 <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
  <title>Atributos</title>
  <sect1 xml:id="language.attributes.overview">
   <title>Descripción general de atributos</title>
   <?phpdoc print-version-for="attributes"?>

   <para>
    Los atributos de PHP ofrecen metadatos estructurados y legibles por máquinas para clases, métodos,
    funciones, parámetros, propiedades y constantes. Pueden ser inspeccionados en tiempo de ejecución
    a través de la <link linkend="book.reflection">API de Reflection</link>, lo que permite un
    comportamiento dinámico sin modificar el código. Los atributos proporcionan una forma declarativa de anotar
    el código con metadatos.
   </para>
   <para>
    Los atributos permiten desacoplar la implementación de una funcionalidad de su uso. Mientras que
    las interfaces definen la estructura mediante la imposición de métodos, los atributos proporcionan metadatos en
    varios elementos, incluidos métodos, funciones, propiedades y constantes. A diferencia de las interfaces,
    que obligan a implementar métodos, los atributos anotan el código sin alterar su estructura.
   </para>
   <para>
    Los atributos pueden complementar o reemplazar métodos opcionales de una interfaz al proporcionar metadatos en lugar de
    una estructura impuesta. Considera una interfaz <literal>ActionHandler</literal> que representa una
    operación en una aplicación. Algunas implementaciones pueden necesitar un paso de configuración, mientras que otras no.
    En lugar de obligar a todas las clases que implementan <literal>ActionHandler</literal> a definir un
    método <literal>setUp()</literal>, un atributo puede indicar los requisitos de configuración. Este enfoque
    aumenta la flexibilidad, permitiendo que los atributos se apliquen varias veces cuando sea necesario.
   </para>

   <example>
    <title>Implementación de métodos opcionales de una interfaz mediante atributos</title>
     <programlisting role="php">
<![CDATA[
<?php
interface ActionHandler
{
    public function execute();
}

#[Attribute]
class SetUp {}

class CopyFile implements ActionHandler
{
    public string $fileName;
    public string $targetDirectory;

    #[SetUp]
    public function fileExists()
    {
        if (!file_exists($this->fileName)) {
            throw new RuntimeException("El archivo no existe");
        }
    }

    #[SetUp]
    public function targetDirectoryExists()
    {
        if (!file_exists($this->targetDirectory)) {
            mkdir($this->targetDirectory);
        } elseif (!is_dir($this->targetDirectory)) {
            throw new RuntimeException("El directorio de destino $this->targetDirectory no es un directorio");
        }
    }

    public function execute()
    {
        copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
    }
}

function executeAction(ActionHandler $actionHandler)
{
    $reflection = new ReflectionObject($actionHandler);

    foreach ($reflection->getMethods() as $method) {
        $attributes = $method->getAttributes(SetUp::class);

        if (count($attributes) > 0) {
            $methodName = $method->getName();

            $actionHandler->$methodName();
        }
    }

    $actionHandler->execute();
}

$copyAction = new CopyFile();
$copyAction->fileName = "/tmp/foo.jpg";
$copyAction->targetDirectory = "/home/user";

executeAction($copyAction);
]]>
     </programlisting>
    </example>
  </sect1>

  <sect1 xml:id="language.attributes.syntax">
   <title>Sintaxis de atributos</title>

   <para>
    La sintaxis de atributos consta de varios componentes clave. Una declaración
    de atributo comienza con <literal>#[</literal> y termina con
    <literal>]</literal>. Dentro de esta, se pueden listar uno o más atributos,
    separados por comas. El nombre del atributo puede ser no cualificado, cualificado
    o totalmente cualificado, como se describe en <link linkend="language.namespaces.basics">Uso de los espacios de nombres: lo básico</link>.
    Los argumentos para el atributo son opcionales y se encierran entre paréntesis
    <literal>()</literal>. Los argumentos solo pueden ser valores literales o expresiones
    constantes. Se admite la sintaxis de argumentos posicionales y nombrados.
   </para>

   <para>
    Los nombres de los atributos y sus argumentos se resuelven en una clase, y los argumentos
    se pasan a su constructor cuando se solicita una instancia del atributo
    a través de la API de Reflection. Por lo tanto, se recomienda crear una clase
    para cada atributo.
   </para>

   <example>
    <title>Sintaxis de atributos</title>

    <programlisting role="php">
<![CDATA[
<?php
// a.php
namespace MyExample;

use Attribute;

#[Attribute]
class MyAttribute
{
    const VALUE = 'value';

    private $value;

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

// b.php

namespace Another;

use MyExample\MyAttribute;

#[MyAttribute]
#[\MyExample\MyAttribute]
#[MyAttribute(1234)]
#[MyAttribute(value: 1234)]
#[MyAttribute(MyAttribute::VALUE)]
#[MyAttribute(array("key" => "value"))]
#[MyAttribute(100 + 200)]
class Thing
{
}

#[MyAttribute(1234), MyAttribute(5678)]
class AnotherThing
{
}
]]>
    </programlisting>
   </example>
  </sect1>


  <sect1 xml:id="language.attributes.reflection">
   <title>Lectura de atributos con la API de Reflection</title>

   <para>
    Para acceder a los atributos de clases, métodos, funciones, parámetros, propiedades
    y constantes de clase, utiliza el método <function>getAttributes</function> proporcionado
    por la API de Reflection. Este método devuelve un array de instancias de <classname>ReflectionAttribute</classname>.
    Estas instancias pueden consultarse para obtener el nombre del atributo, los argumentos, y
    también pueden usarse para instanciar una instancia del atributo representado.
   </para>

   <para>
    Separar la representación reflejada del atributo de su instancia real proporciona un mayor
    control sobre la gestión de errores, como clases de atributos faltantes, argumentos mal escritos,
    o valores ausentes. Los objetos de la clase de atributo se instancian solo después de llamar a
    <function>ReflectionAttribute::newInstance</function>, lo que garantiza que la validación de los argumentos
    se realice en ese momento.
   </para>

   <example>
    <title>Lectura de atributos con la API de Reflection</title>

    <programlisting role="php">
<![CDATA[
<?php

#[Attribute]
class MyAttribute
{
    public $value;

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

#[MyAttribute(value: 1234)]
class Thing
{
}

function dumpAttributeData($reflection) {
    $attributes = $reflection->getAttributes();

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpAttributeData(new ReflectionClass(Thing::class));
/*
string(11) "MyAttribute"
array(1) {
  ["value"]=>
  int(1234)
}
object(MyAttribute)#3 (1) {
  ["value"]=>
  int(1234)
}
*/

]]>
    </programlisting>
   </example>

   <para>
    En lugar de iterar sobre todos los atributos en la instancia de reflexión,
    puedes recuperar solo aquellos de una clase de atributo específica pasando
    el nombre de la clase de atributo como argumento.
   </para>

   <example>
    <title>Lectura de atributos específicos utilizando la API de Reflection</title>

    <programlisting role="php">
<![CDATA[
<?php

function dumpMyAttributeData($reflection) {
    $attributes = $reflection->getAttributes(MyAttribute::class);

    foreach ($attributes as $attribute) {
       var_dump($attribute->getName());
       var_dump($attribute->getArguments());
       var_dump($attribute->newInstance());
    }
}

dumpMyAttributeData(new ReflectionClass(Thing::class));
]]>
     </programlisting>
    </example>
  </sect1>

  <sect1 xml:id="language.attributes.classes">
   <title>Declaración de clases de atributos</title>

   <para>
    Se recomienda definir una clase separada para cada atributo. En el caso más simple,
    una clase vacía con la declaración <literal>#[Attribute]</literal> es suficiente.
    El atributo puede ser importado desde el espacio de nombres global utilizando una declaración
    <literal>use</literal>.
   </para>

  <example>
   <title>Clase de atributo simple</title>

   <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute]
class MyAttribute
{
}
]]>
   </programlisting>
  </example>

  <para>
   Para restringir los tipos de declaraciones a los que se puede aplicar un atributo,
   pasa una máscara de bits como primer argumento en la declaración
   <literal>#[Attribute]</literal>
  </para>

  <example>
   <title>Usar la especificación de destino para restringir dónde se pueden usar los atributos</title>

   <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
class MyAttribute
{
}
]]>
    </programlisting>

    <para>
     Declarar <classname>MyAttribute</classname> en otro tipo ahora generará una excepción durante
     la llamada a <function>ReflectionAttribute::newInstance</function>
    </para>
   </example>

   <para>Los siguientes destinos se pueden especificar:</para>

   <simplelist>
    <member><constant>Attribute::TARGET_CLASS</constant></member>
    <member><constant>Attribute::TARGET_FUNCTION</constant></member>
    <member><constant>Attribute::TARGET_METHOD</constant></member>
    <member><constant>Attribute::TARGET_PROPERTY</constant></member>
    <member><constant>Attribute::TARGET_CLASS_CONSTANT</constant></member>
    <member><constant>Attribute::TARGET_PARAMETER</constant></member>
    <member><constant>Attribute::TARGET_ALL</constant></member>
   </simplelist>

   <para>
    Por defecto, un atributo solo se puede usar una vez por declaración. Para permitir
    que un atributo sea repetible, especifícalo en la máscara de bits de la
    declaración <literal>#[Attribute]</literal> utilizando el
    flag <constant>Attribute::IS_REPEATABLE</constant>
   </para>

   <example>
    <title>Usar IS_REPEATABLE para permitir que un atributo se use varias veces en una declaración</title>

    <programlisting role="php">
<![CDATA[
<?php

namespace Example;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class MyAttribute
{
}
]]>
    </programlisting>

   </example>
  </sect1>
 </chapter>

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