Atributos PHP foram introduzidos no PHP 8.0. Esta versão marcou um marco significativo para a linguagem, trazendo diversas novidades e melhorias, incluindo a introdução de atributos para adição de metadados às declarações de código.

A primeira vez que tive que lidar com atributos foi devido a um problema na biblioteca PHP do Inspetor. Verifique no GitHub. Antes de nos aprofundarmos na solução, vamos dar uma visão geral do que são atributos e como eles podem ser usados ​​em seu código PHP.

Atributos são um recurso poderoso que permite adicionar metadados a declarações como classes, métodos ou propriedades. Esses metadados podem ser recuperados programaticamente, abrindo novas possibilidades para um código mais limpo, organizado e eficiente.

Lembre-se, os atributos não têm efeito em tempo de execução. Eles estarão disponíveis nas APIs do Reflection para alertar seu aplicativo sobre coisas que você deseja executar com base em atributos anexados a uma classe, método ou propriedade.

Atributos integrados

PHP vem com vários atributos integrados que atendem a diferentes propósitos. Aqui estão alguns notáveis:

@obsoleto

Marca uma função ou método como obsoleto, sinalizando que deve ser evitado, pois pode ser removido em versões futuras.

#[Deprecated("Use newFunction() instead")]
function oldFunction() 
{
    // Function implementation
}

@substituir

Garante que o método em uma classe filha se destina a substituir um método na classe pai.

class Child extends Parent {
    #[Override]
    public function defaultMethod() 
    {
        // Method implementation
    }
}

Se defaultMethod() eventualmente mudar seu nome na classe pai, isso não será mais uma substituição. Neste caso, o PHP irá gerar um aviso porque declaramos explicitamente que esperamos ser uma substituição e nos alertará sobre o desalinhamento.

De qualquer forma, um bom IDE deve nos permitir não incorrer neste tipo de erros.

@SuppressWarnings

Suprime avisos específicos para um determinado trecho de código.

#[SuppressWarnings("SomeWarning")]
function someFunction() 
{
    // Function implementation
}

Criando classes de atributos personalizados

Agora, vamos criar uma classe de atributos personalizados. Isso é benéfico quando você deseja encapsular um comportamento específico dentro de um atributo.

#[Attribute]
class CustomAttribute 
{
    public string $message;

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

Você pode então usar este atributo personalizado em vários elementos:

class MyClass 
{
    #[CustomAttribute("This is a custom attribute")]
    public $myProperty;

    #[CustomAttribute("Another custom attribute")]
    public function myMethod() 
    {
        // Method implementation
    }
}

Exemplos de uso

Vamos explorar um exemplo prático. Suponha que você esteja construindo um aplicativo da web e queira criar um atributo personalizado para definir o comprimento de uma string:

#[Attribute(Attribute::TARGET_PROPERTY)]
class MaxLength 
{
    public int $maxLength;

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

No exemplo acima, restringimos a capacidade de aplicar o atributo apenas às propriedades da classe. Agora podemos usá-lo na classe User:

class User 
{
    #[MaxLength(20, message: "Username must be 20 characters or less")]
    public string $username;

    // Other properties and methods
}

Conforme mencionado antes, adicionar o atributo à propriedade não tem impacto durante a execução. Mas agora podemos recuperar essas informações usando reflexão para eventualmente tomar alguma ação.

Adoção por frameworks PHP

Os frameworks PHP mais utilizados como Symfony e Laravel já estão adotando atributos para substituir basicamente "Anotações". No Symfony 5.2 ou superior você pode declarar um controlador e conectá-lo a uma rota usando atributos:

public class Arrayable implements \ArrayAccess
{
    …

    public function offsetExists($offset)
    {
        return isset($this->data[$offset]);
    }

    …
}

Desde o PHP 8 a definição da interface ArrayAccess mudou para:

Com o uso de atributos eles reforçaram a declaração do tipo de dados para os argumentos nas funções de deslocamento. Usando o atributo LanguageLevelTypeAware, se a implementação não fornecer o tipo de dados para os argumentos, ela dispara um "aviso de descontinuação".

Mas declarar o tipo de dados em argumentos de função quebra a compatibilidade com versões mais antigas do PHP que não suportam declaração de tipo de dados de argumentos.

Como era apenas um aviso para mudanças futuras, resolvemos o problema com outro atributo integrado do PHP para suprimir o aviso:

public class Arrayable implements \ArrayAccess
{
    …

    #[\ReturnTypeWillChange]
    public function offsetExists($offset)
    {
        return isset($this->data[$offset]);
    }

    …
}

O atributo ReturnTypeWillChange simplesmente informa ao PHP que sabemos sobre as mudanças futuras na linguagem e que já planejamos as atualizações necessárias.

Para esta mudança em particular elas serão definitivamente implementadas no PHP 9.

Lembre-se de usar atributos criteriosamente, mantendo sua base de código limpa e bem documentada. Isto é particularmente crucial no desenvolvimento de produtos SaaS, onde escalabilidade, capacidade de manutenção e eficiência são fundamentais.

Novo no Inspetor? Monitore seu aplicativo gratuitamente

Inspector é uma ferramenta de monitoramento de execução de código projetada especificamente para desenvolvedores de software. Você não precisa instalar nada no nível do servidor, basta instalar o pacote do compositor e você está pronto para começar.

Ao contrário de outras plataformas complexas e completas, o Inspector é super fácil e compatível com PHP. Você pode experimentar nosso pacote Laravel ou Symfony.

Se você procura automação eficaz, insights profundos e a capacidade de encaminhar alertas e notificações para seu ambiente de mensagens, experimente o Inspector gratuitamente. Registre sua conta.

Ou saiba mais no site: https://inspector.dev