PHP OOP - Using annotations and attributes

Introduction

Annotations let you add metadata to classes, class methods, and class properties, and class method parameters. This metadata is often used to provide a bit more information or a bit of configuration data.

Annotations were added to the Java programming language around 2004, but it took until 2020 for annotations to be formally added to PHP 8 under the name Attributes.

Before PHP 8, applications and frameworks such as Drupal that wanted to use the concept of annotations had to rely on third-party libraries such as Doctrine\Annotations.

If you're writing code in PHP 8 or higher, you should no longer use annotations, but switch to the new built-in PHP Attributes system.

In this unit you will learn how to use existing attributes. 

However we will not cover how to define new attributes and their underlying code, as that builds on reflection, a more advanced concept that is outside the scope of this unit.

Using an attribute

At the time of writing, PHP 8 does not provide any built-in Attributes like Java does. Any attribute you would like to use must be provided by custom code or a third-party library. 

Example

Assume you are using a PHP framework that makes an attribute named Deprecated available for you to use.

Assume that the documentation informs you that you that you should use that attribute on all of the functions in your custom code that will no longer exist in future versions of your code.

Also assume that the documentation specifies that you can use the attribute on its own, or with a custom message like "This function will be removed in version 4.".

Based on this documentation, you can use the Deprecated attribute in the following two ways in your custom code:

#[Deprecated]
function connectToDabase() {
  // Implementation goes here.
}

and

#[Deprecated("This function will be removed in version 4.")]
function connectToDabase() {
  // Implementation goes here.
}

As you can see, this attribute does not change the way the connectToDatabase() function behaves, but provides more information about the function. 

In addition, the attribute's documentation clarifies that a PHP warning will be emitted if you use this function. 

The second example also provides a little bit of configuration in the form of the exact message to be raised when this function is used.

Refer to your code or framework's documentation to learn which attributes are available, if any, and how to use them.

Again, you can also create your own attributes, but that's beyond the scope of this unit.

Annotations vs attributes.

Attributes and annotations are conceptually the same thing. They both provide metadata to classes and methods, and then let you act on that metadata later on.

If you wanted to use annotations before PHP 8, you had no choice but to use one of the available third-party annotation libraries because the PHP language did not have the concept of annotations built-in.

With PHP 8 came the Attribute syntax, which is PHP's official answer of and replacement for annotations.

Frameworks like Drupal that use annotations are now replacing those annotations with attributes.

Here's an example of how you used to create custom blocks in Drupal 8+ using annotations, and the newer syntax to do the same thing using attributes:

Annotation

Using an Annotation to define a custom Drupal 8+ block (outdated):

Attribute

Using an Attribute to define a custom Drupal 8+ block (recommended)

This example shows how Attributes work exactly the same as Annotations did. 

The only differences are:

• Annotations were not officially part of the PHP language specification, while Attributes are.
• Attributes have a slightly different syntax than Annotations.