13

Ultimamente venho me deparando com alguns trechos de código que não consigo entender o propósito deles, geralmente são usados dentro de comentarios, o que não faz muito sentido pra mim.

Fazendo uma pesquisa sobre esse assunto cai no termo atributos, mas mesmo depois disso não consegui entender bem a razão deles. O uso do termo atributos pra se referir a variáveis também atrapalha bastante na busca.

No site oficial do PHP, além de outras definições, entendi que não é algo exclusivo do PHP e que na verdade eh bem comum.

Similar concepts exist in other languages named Annotations in Java, Attributes in C#, C++, Rust, Hack and Decorators in Python, JavaScript.

Um exemplo de código:

/**
* @Route("/api/posts/{id}", methods={"GET", "HEAD"})
*/
class User
{

Que na versao 8.0 do PHP fica

#[Route("/api/posts/{id}", methods: ["GET", "HEAD"])]
class User
{

Ou ate mesmo na extensão que eu uso pra gerar os getters e setters automaticamente:

/**
* Set the value of name
*
* @return  self
*/ 
public function setName($name)
  {
      $this->name = $name;

      return $this;
  }

Nesse último caso eu sempre acabo apagando esses atributos.

Qual a função deles? eles são necessários/fundamentais ou soh eh algo a mais pra ajudar na compilação/manutenção do código? Devo sempre os utilizar?

2
  • O Symfony Framework costumava utilizar docblock, já que o PHP não tinha um suporte nativo a atributos. Acredito que internamente era usado o ReflectionFunctionAbstract::getDocComment para extrair essas informações e transformá-las em parte funcional do código. Atualmente, com na implementação do PHP 8, você também precisa usar Reflection para obter esses dados, porém sem a necessidade de fazer parser de string do docblock. Commented 23/12/2020 às 13:18
  • o @return self é usado pelo editor de código para permitir o uso da função de autocompletar Commented 24/01/2021 às 1:58

1 Resposta 1

9

Eles são usados como comentário porque a linguagem não suporta isso oficialmente, então você coloca como um texto que seria descartado no código, mas alguma ferramenta lê esse código e sabe que aquilo precisa de um tratamento. Essa ferramenta é praticamente um compilador.

Eles servem para informar algo sobre o código que essa ferramenta precisa para tomar decisões e executar certas tarefas. Em geral essas ferramentas gem código ou processam algo baseado nessas informações, poupando o programador de executar um trabalho maçante ou "sórdido" e repetitivo.

Exemplo

No exemplo é estabelecido qual é a rota que aquele método deve responder. Você não precisa escrever um código que faça isso, já existe um código no framework que está usando que lê essas atributos e vincula a roda com o método e a chamada é realizada pelo mecanismo de roteamento sem maiores trabalhos. Sem o atributo você teria que escrever um código em algum lugar, no mínimo montando um array com as rotas e os métodos a chamar. E teria que sempre manter isso e os métodos que escreveu de forma sincronizada, o que é propenso a erros.

Um outro exemplo muito comum é dar alguma validação para aquilo, ou dar um nome mais palatável para o usuário, ou mudar o comportamento padrão daquele método ou tipo ou outro artefato do código.

O último exemplo parece ser algo de documentação e não um atributo.

PHP 8

Em PHP 8 criaram uma sintaxe oficial para isso e não precisa mais por nos comentários. Isso pode trazer algumas vantagens porque não precisará de nada externo para cuidar disso. Eu não conheço detalhes da implementação, mas pode ser que essa informação continue disponível no código mesmo durante a execução. Precisaram fazer isso porque nessa versão o código pode ser executado sem fonte, então o comentário seria descartado. E estando disponível durante a execução pode ser usado com reflexão.

Conclusão

Eles são necessários para facilitar o trabalho do framework que está usando. Em geral dá para fazer de outra forma, mas pode dar muito mais trabalho. Se tirar e não tiver outra forma programada para cuidar daquilo provavelmente não funcionará como o esperado, mas aí é caso a caso. O mecanismo é muito simples, a forma de usar pode ser complexa, não depende da linguagem, depende da peça de software que faz alguma coisa com ele.

Pode ser útil (mesmo quando fala de outras linguagens):

Coloquei no GitHub para referência futura.

3
  • Entendi, mas e no caso do @return self, considerando que esse atributo seria apenas da classe q eu estou criando e nao parte de algum framework, seria necessario utiliza-lo?
    – Vrrl
    Commented 26/11/2020 às 18:29
  • 2
    Isso não parece ser um atributo, pode ser só algo ligado à documentação.
    – Maniero
    Commented 26/11/2020 às 18:34
  • 1
    @Vrrl O @return trata-se apenas de uma parte do DocBlock. Ele é usado apenas para documentar o que vai ser retornado nos métodos/funções. Talvez algumas extensões de IDE utiliza-os para trazer informações de autocomplete. Commented 23/12/2020 às 13:11

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .