PHP annotations

 Annotations are meta-data that can be embedded in source code.

You may already be familiar with the PHP-DOC flavor of source code annotations, which are seen in most modern PHP codebases - they look like this:

class Foo

{

  /**

   * @var integer

   */

  public $bar;

}

When you see @var integer in the source code, immediately preceding the public $bar declaration, this little piece of meta-data tells us that the $bar property is expected to contain a value of type integer.

This information is useful to programmers - an IDE can use this information to display popup hints when you’re writing code that works with an instance of Foo, documentation generators can display this information in reference material, etc.

Now imagine you had to build an HTML form that allows someone to edit a Foo object. When this information comes back from a form-post, you will need to validate that the input is in fact an integer - using the information from the @var annotation, you could abstract and automate this process, rather than having to code in by hand every time.

The same information about the type of value required for this property could have many other uses besides validation - for example, you could use it to decide what type of input to render on a form, or how to persist the value to a database column.

Using other types of annotations besides @var, you could provide more information about the $bar property - for example, you might use an annotation to specify the minimum and maximum allowed integer values of a property for validation, or define a label to be displayed next to the input on forms or in the column-header of a list of Foo objects:

class Foo

{

  /**

   * @var integer

   * @range(0, 100)

   * @label('Number of Bars')

   */

  public $bar;

}

We now have the information about the type of value, the allowed range, and the label, all associated with the Foo::$bar property member. You may have noticed a subtle difference between the @var annotation and the other two annotations in this example: the extra parentheses - we’ll get to that below.

It’s important to understand that this meta-data does not have a single predefined purpose - it is general information, which when put to use in creative ways, can be used to simplify or eliminate repetitive work, and enables you to write more elegant and reusable code.

Annotations in Drupal 8 - 

Annotations are another  new concept in Drupal 8 to wrap your head around. Annotations are 

Annotations are used by other PHP projects. For example, Symfony2 uses annotations for routing rules and Doctrine uses them for ORM related meta data. written as PHP code comments above a class or function and contain metadata about the function or class.

As it stands, Annotations are only used by the Plugin system in Drupal 8. They provide the mechanism for which Plugins are discovered by Drupal and describe their meta data.

Plugin  - 

One of the major conceptual changes in Drupal 8 is that Drupal is not aware of your code until you specifically tell it about your code.

In module development you tell Drupal about the module in a info.yml file. You tell Drupal about specific routes in route YAML files. You tell Drupal which menu links to add to the menu system in menu YAML files. Annotations are a similar concept for Plugins. Rather than having a YAML file for each plugin, you have an annotation and Drupal will automatically find (discover) the plugin.

Example plugin type - 

Blocks are the most common type of plugin in Drupal 8. But they are by no means the only type. Plugins include.

A - Blocks

B- Field Formatters

C- Views Plugins

D- Conditions 

E- Migrate Source

See Drupal.org for more information on Annotation-based plugins.

Example annotations - 

Example of an annotation for a block class.

----------------------------------------------------------

/**

 * Provides a 'Welcome' Block

 *

 * @Block(

 *   id = "welcome_block",

 *   admin_label = "Welcome block",

 * )

 */

--------------------------------------------------------

Block manager scans files looking for @Block annotation tag to find block instances.

The @Block annotation ensures that the block manager discovers this custom block and makes it available to be added to a region. The id of welcome_block is the machine name and the admin_label (Hello block) will appear in the block interface’s list of blocks.

Annotation parser - 

Annotations are read and parsed at runtime by an annotation engine. Drupal 8 uses the Doctrine annotation parser, which turns it into an object that PHP can use.