What are attributes in PHP? (Annotations/Attributes/Decorators)

Asked

Viewed 200 times

12

Lately I have come across some snippets of code that I can’t understand their purpose, are usually used within comments, which doesn’t make much sense to me.

Doing research on this subject falls in the term attributes, but even after that I couldn’t quite understand their reason. The use of the term attributes to refer to variables also hinders a lot in the search.

On the official website of PHP, in addition to other definitions, I understood that it is not something exclusive of PHP and that in fact it is very common.

Similar Concepts exist in other Languages named Annotations in Java, Attributes in C#, C++, Rust, Hack and Decorators in Python, Javascript.

An example of code:

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

That in version 8.0 of PHP is

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

Or even the extension I use to generate the getters and setters automatically:

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

      return $this;
  }

In the latter case I always end up deleting these attributes.

What is their function? Are they necessary/fundamental or is soh something else to help compile/maintain the code? Should I always use them?

php attributes annotation php-8

  • Symfony Framework used to use docblock, since PHP did not have native attribute support. I believe that in-house docblock was used ReflectionFunctionAbstract::getDocComment to extract that information and make it a functional part of the code. Currently, with the implementation of PHP 8, you also need to use Reflection to get this data, but without the need to parse docblock’s string.

  • the @return self is used by the code editor to allow use of the autocomplete function

2 answers

9


They’re used as commentary because the language doesn’t officially support it, so you put it as a text that would be discarded in the code, but some tool reads that code and knows that it needs a treatment. This tool is practically a compiler.

They serve to inform something about the code that this tool needs to make decisions and perform certain tasks. In general, these tools use code or process something based on this information, saving the programmer from performing dull or "nasty" and repetitive work.

Example

In the example it is established which is the route that that method should respond to. You do not need to write a code that does this, there is already a code in the framework which is using which reads these attributes and links the wheel with the method and the call is performed by the routing mechanism without further work. Without the attribute you would have to write a code somewhere at least by mounting a array with the routes and methods to call. And would always have to keep this and the methods you wrote synchronized, which is prone to errors.

Another very common example is to give some validation to that, or give a more palatable name to the user, or change the default behavior of that method or type or other artifact of the code.

The last example seems to be something of documentation and not an attribute.

PHP 8

In PHP 8 they created an official syntax for this and no longer need to put in the comments. This can bring some advantages because you won’t need anything external to take care of it. I don’t know the details of the implementation, but it may be that this information remains available in the code even during execution. They had to do this because in this version the code can be executed without source, so the comment would be discarded. And being available during execution can be used with reflection.

Completion

They are necessary to facilitate the work of framework that you’re using. You can usually do it another way, but it can be a lot more work. If you take it and you don’t have another way to handle it, it probably won’t work as expected, but that’s case by case. The mechanism is very simple, the way to use can be complex, does not depend on the language, depends on the piece of software that does something with it.

Can be useful (even when speaking other languages):

  • I understood, but in the case of @Return self, considering that this attribute would be only of the class q I am creating and not part of some framework, it would be necessary to use it?

  • 2

    That doesn’t seem to be an attribute, it might just be something related to the documentation.

  • 1

    @Vrrl O @return It is only a part of Docblock. It is only used to document what will be returned in the methods/functions. Maybe some IDE extensions use them to bring autocomplete information.

-1

It is called docblock or Docblock that is used to document your code. This post explains well what its purpose is Phpdoc - What is, what is useful and how to use? . The use of it has become popular within frameworks, so some will put Docblock as the default.

Browser other questions tagged php attributes annotation php-8

You are not signed in. Login or sign up in order to post.