Como usar Attributes/Annotations no PHP 8

Nesse artigo vamos conhecer o que são annotations no PHP 8, como usar esse recurso e também como implementar a parte de obtenção dos valores dos attributes.

Curso PHP - Novidades do PHP 8.0

Conhecer o curso

O que são Annotations

Annotations ou no caso do PHP também chamado de Attributes, é um modo que temos de declararmos meta informações a respeito de um determinado elemento de código. Podemos declarar meta informações sobre uma propriedade, um método ou uma classe. Veja um pseudo código abaixo:

@entidade
class Carro
{
    @validacao(min: 1990, max: 2015)
    propriedade inteira ano;

    @acao
    funcao andar(velocidadeMaxima)
    {}
}

No exemplo acima temos as seguintes meta informações:

• @entidade - é uma anotação da classe Carro, que poderia indicar que ela é uma entidade da aplicação.
• @validacao - é uma anotação da propriedade, nesse exemplo está indicando que os valores válidos para essa propriedade devem ser entre 1990 e 2015.
• @acao - anotação do método, poderia ser utilizado para indicar que esse método realiza uma ação e notificar algum outro trecho de código.

Annotations antes do PHP 8

Mesmo antes do PHP 8 alguns projetos já utilizavam o conceito na linguagem, porém esse processo era realizado de maneira não oficial. As annotations eram definidas dentro de blocos de comentários, com base nisso eles liam esses arquivos e obtinham as meta informações.

Se você já trabalhou com Symfony ou Doctrine provavelmente já utilizou annotations, mesmo em versões anteriores do PHP. Veja o seguinte código utilizado no Doctrine:

/**
 * @ORM\Entity(repositoryClass="App\Repository\TaskRepository")
 */
class Task
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=100)
     * @Assert\Length(
     *      min = 5,
     *      minMessage = "length.min"
     * )
     * @HasString(
     *      string = "Elton"
     * )
     */
    private $title;
}

Annotations no PHP 8

A partir da versão 8 do PHP as annotations ou como foi chamado na linguagem “attributes”, ganharam uma implementação nativa e padronizada. A sintaxe definida para sinalizar um atributo ficou:

#[AnotacaoSemParametro]

E quando necessário enviar algum parâmetro:

#[AnotacaoComParametro(parametro1: valor, parametro2: valor)]

Será possível usar attributes no PHP 8 para classes, métodos e propriedades.

No Symfony 5.2 já será possível substituir as annotations antigas pelos attributes do php 8:

class SomeController
{
    #[Route('/path', name: 'action')]
    public function someAction()
    {
        // ...
    }
}

Formação Desenvolvedor PHP

Conhecer a formação

Como obter valores dos attributes no php 8

Se você for apenas usar bibliotecas externas para declarar meta informações sobre seu código, a sintaxe que aprendemos até agora já é suficiente. Agora se quiser criar suas próprias anotações personalizadas, precisará usar um pouco da API de reflection do PHP.

Vamos supor que deseja validar os dados das propriedades de uma classe usando anotações:

class Carro {
    #[Validacao('max', 110)]
    public int $velocidade;
}

Nesse caso a primeira coisa que precisa ter em mente é que o nome da annotation que usamos no PHP é o nome de uma classe e os parâmetros passados são enviados no construtor. No exemplo acima, usamos a seguinte classe para representar essa anotação:

#[Attribute]
class Validacao {
    public function __construct(
        public string $regra,
        public int $valor
    ){}
}

Então para pegarmos as meta informações definida nos attributos podemos fazer:

//Cria uma instância de classe reflection com as informações da classe Carro
$informacoesClasseCarro = new reflectionClass(Carro::class);

//Percorre as propriedades da classe Carro
foreach ($informacoesClasseCarro->getProperties() as $propriedade) {
    //Mostra o nome da propriedade	
    echo $propriedade->getName() . ': ';

    //Pega os atributos dessa propriedade em especifico
    $atributosDaPropriedade = $propriedade->getAttributes(Validacao::class);
    //Percorre os atributos definidos na propriedade
    foreach ($atributosDaPropriedade as $atributo) {
        //Cria uma instância da classe que representa a anotação, nesse caso a classe Validacao
        var_dump($atributo->newInstance());
    }
}

O código que usamos acima basicamente já existia nas versões anteriores do PHP, único código diferente é o método getAttributes que foi criado justamente para obter os dados de atributo de uma classe, método ou propriedade.

No Github da Treinaweb têm esse exemplo completo de Attributes, mostrando também como realizar a validação usando a meta informações que definimos lá na propriedade $velocidade da classe Carro.

Formação Desenvolvedor PHP

Conhecer a formação

Considerações Finais

A implementação do recurso de Attributes ou também conhecido como Annotations no PHP 8 é algo muito positivo. Várias bibliotecas e ferramentas já estão definindo usos bem interessantes para esse recursos mesmo antes do lançamento oficial da versão 8 do PHP. O que indica que dentro de algum tempo teremos um uso em massa desse recurso.