Should we use PHP Annotations?

Today we will talk about php annotations.

What is it good for?

Annotations basically let you inject behavior and can promote decoupling.

In my words I’d say that these annotations are valuable especially in context of reflection where you gather (additional) metadata about the class/method/property you are inspecting.

Who is using it ?

Most of PHP’s bigboys are using Annotations.

most popular frameworks using annotation

One example would be the Doctrine ORM. Because of the use of annotations you do not have to inherit from a Doctrine-specific class unlike the Propel ORM.

Annotations in Doctrine

Take a look at the above picture. The left part was writed using annotation and the right part was created with the .yaml settings

Another example instead of ORM: Dependency Injection frameworks. The upcoming FLOW3 framework for example uses docComments/annotations to identify which objects are injected in an instance created from a DI container instead of specifying it in an XML configuration file.

Oversimplified example following:

You have two classes, one Soldier class and a Weapon class. A Weapon instance gets injected in a Soldier instance.

You can do that with xml as below.

<class name="Soldier">
    <!-- call setWeapon, inject new Weapon instance -->
    <call method="setWeapon">
        <argument name="Weapon" />
    </call>
</class>

class Soldier {
    ...

    // ---> this

    /**
     * @inject $weapon Weapon
     */
    public function setWeapon($weapon) {
        $this->weapon = $weapon;
    }

    ...

isn’t that easier ? i think it is.

Why do i like Annotations?

Configuration in object!

when you use external configuration files you will have deal with more complexity.

It is documented/stored by PHPDocumentor

So i don’t have to write a api documentation for every annotation. it is done easily by PHPDOC.

it is documented by phpdocumentor

The downside or why not ?

Lets look at the downside of annotations.

But it is code, in comments!

if that is true, using annotations would be really horrible idea, Because code comments should never be necessary for a script to function properly. Code comments are exactly that — comments. Their purpose is to provide commentary on the code, not to provide logic that is critical to the application’s functionality.

This is not a correct approach, we write annotations in docblock. Comments and annotations are completely different things.

the correct sentence should be as follows:

But it is code, in docblocks!

// this is a comment

/**
 *
 * this is a docblock
 * 
 */ 

docblocks are first class citizens!

Its impossible to debug/test

Unfortunately that is a side effect like most/all actions of decoupling such as design patterns, data translations, etc.

Of course there are some frameworks for annotation testing but annotation debugging still very difficult.

Hard to integrate with IDEs

Unfortunately this is also true, there is no annotation support in any ide or editor.

There is a plugin for PHPStorm that you can use.

unless you are a PHPStorm user,writing annotations would be very painful for you.

Reliance on Yet Another Library

If you use annotations, your application is now dependant on a library that parses annotations (doctrine/common, most likely). I’m sure quite a number of development hours were/are spent writing and bugfixing that library, all of which could have been spent on other projects.

It does not perform!

this is not a correct approach either! You can always use caching for this process.

Conclusion

Annotations provide us simplicity and legibility but comes with some downsides e.g lack of testing.

I think using annotation will make your job easier unless code testabilty is a priority for you.