Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How are PHP attributes different from doc block annotations?

Lately, the attributes RFC has passed the voting stage. How they are different from DocBlock annotations, and what benefits will they bring?

Consider simple Doctrine entity, before:

/**
 * @ORM\Entity
 */
class Entity {
    // …
}

After, using native PHP attributes:

#[ORM\Entity]
class Entity {
    // …
}
like image 462
emix Avatar asked Apr 27 '20 12:04

emix


People also ask

How do I add annotations to my DocBlock?

Using Doctrine annotations, you write annotations in your docblocks: The Type part is actually a class. It must be declared in the use statements at the top of your file. Heads up! We strongly recommend using an IDE that has Doctrine annotations support. Starting with PHP 8, PHP got native annotations support.

What is the correct syntax for @PHP-Doc annotations?

PHP-DOC annotations do not have a fixed syntax - that is, everything after @name is interpreted differently for each type of annotation. For example, the syntax for @var is @var {type} {description}, while the syntax for @param is @param {type} {$name} {description}.

What are the different types of annotations in PHP?

There are various kinds of annotations like the @var and @int types which can be used for specific uses as their name itself suggests. PHP annotations are used by giving @ prefix and its syntax is as follows:

What happened to doctrine annotations in PHP?

Doctrine annotations are deprecated in favor of native PHP 8 attributes. Support will be dropped in a future release. Historically, attributes were not available in PHP and PHP developers had to "trick" PHP to get annotation support. This was the purpose of the doctrine/annotation library.


1 Answers

The explanation at this part of the RFC: Why not extending Doc Comments? explains a lot of the benefits

  • Namespacing prevents conflicts between different libraries using the same doc comment tag
  • Checking for attribute existence is a O(1) hash key test compared to unpredictable strstr() performance or even parsing the docblock.
  • Mapping attributes to classes ensures the attributes are correctly typed, reducing a major source of bugs in reliance on docblocks at runtime.
  • There is visible demand for something like annotations based on its common use in so many different tools and communities. However, this will always be a confusing thing for newcomers to see in comments. In addition, the difference between /* and /** is still a very subtle source of bugs.

A lot of these boil down to the fact that attributes can be checked by PHP. Tools can leverage the fact that these attributes are already-parsed metadata visible with reflection, rather than comments that need to be parsed with a custom syntax per tool. IDEs and static analysis tools will be able to guarantee correctness without having to know a specific tool's docblock annotation syntax because the attributes resolve to classes that have to exist and might have further type annotations to add checking.

So:

  • tools that define attributes that they use will benefit from correctness and performances gains because PHP will handle the parsing of these attributes for them
  • tools that analyze PHP will benefit from the easier type-checking guarantees and standards for checking attributes' correctness
  • humans will benefit from these tools' improvements and the fact that documentation and metadata can be better separated
like image 185
Daniel Raloff Avatar answered Nov 10 '22 20:11

Daniel Raloff