Handling Annotations

There are several different approaches to handling annotations in PHP. Doctrine Annotations maps docblock annotations to PHP classes. Because not all docblock annotations are used for metadata purposes a filter is applied to ignore or skip classes that are not Doctrine annotations.

Take a look at the following code snippet:

1
namespace MyProject\Entities;

use Doctrine\ORM\Mapping AS ORM;
use Symfony\Component\Validator\Constraints AS Assert;

/**
 * @author Benjamin Eberlei
 * @ORM\Entity
 * @MyProject\Annotations\Foobarable
 */
class User
{
    /**
     * @ORM\Id @ORM\Column @ORM\GeneratedValue
     * @dummy
     * @var int
     */
    private $id;

    /**
     * @ORM\Column(type="string")
     * @Assert\NotEmpty
     * @Assert\Email
     * @var string
     */
    private $email;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

In this snippet you can see a variety of different docblock annotations:

• Documentation annotations such as @var and @author. These annotations are ignored and never considered for throwing an exception due to wrongly used annotations.
• Annotations imported through use statements. The statement `use Doctrine\ORM\Mapping AS ORM` makes all classes under that namespace available as @ORM\ClassName. Same goes for the import of @Assert.
• The @dummy annotation. It is not a documentation annotation and not ignored. For Doctrine Annotations it is not entirely clear how to handle this annotation. Depending on the configuration an exception (unknown annotation) will be thrown when parsing this annotation.
• The fully qualified annotation @MyProject\Annotations\Foobarable. This is transformed directly into the given class name.

How are these annotations loaded? From looking at the code you could guess that the ORM Mapping, Assert Validation and the fully qualified annotation can just be loaded using the defined PHP autoloaders. This is not the case however: For error handling reasons every check for class existence inside the AnnotationReader sets the second parameter $autoload of class_exists($name, $autoload) to false. To work flawlessly the AnnotationReader requires silent autoloaders which many autoloaders are not. Silent autoloading is NOT part of the PSR-0 specification for autoloading.

This is why Doctrine Annotations uses its own autoloading mechanism through a global registry. If you are wondering about the annotation registry being global, there is no other way to solve the architectural problems of autoloading annotation classes in a straightforward fashion. Additionally if you think about PHP autoloading then you recognize it is a global as well.

To anticipate the configuration section, making the above PHP class work with Doctrine Annotations requires this setup:

1
use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\Common\Annotations\AnnotationRegistry;

AnnotationRegistry::registerFile("/path/to/doctrine/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php");
AnnotationRegistry::registerAutoloadNamespace("Symfony\Component\Validator\Constraint", "/path/to/symfony/src");
AnnotationRegistry::registerAutoloadNamespace("MyProject\Annotations", "/path/to/myproject/src");

$reader = new AnnotationReader();
AnnotationReader::addGlobalIgnoredName('dummy');
2
3
4
5
6
7
8
9

The second block with the annotation registry calls registers all the three different annotation namespaces that are used. Doctrine Annotations saves all its annotations in a single file, that is why AnnotationRegistry#registerFile is used in contrast to AnnotationRegistry#registerAutoloadNamespace which creates a PSR-0 compatible loading mechanism for class to file names.

In the third block, we create the actual AnnotationReader instance. Note that we also add dummy to the global list of ignored annotations for which we do not throw exceptions. Setting this is necessary in our example case, otherwise @dummy would trigger an exception to be thrown during the parsing of the docblock of MyProject\Entities\User#id.

1
$reader = new \Doctrine\Common\Annotations\AnnotationReader();

1
use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\Common\Annotations\PsrCachedReader;

$cache = ... // instantiate a PSR-6 Cache pool

$reader = new PsrCachedReader(
    new AnnotationReader(),
    $cache,
    $debug = true
);
2
3
4
5
6
7
8
9
10

1
use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\Common\Annotations\IndexedReader;

$reader = new IndexedReader(new AnnotationReader());
2
3
4

1
use Doctrine\Common\Annotations\AnnotationRegistry;
use Symfony\Component\ClassLoader\UniversalClassLoader;

AnnotationRegistry::registerLoader(function($class) {
    $file = str_replace("\\", DIRECTORY_SEPARATOR, $class) . ".php";

    if (file_exists("/my/base/path/" . $file)) {
        // file_exists() makes sure that the loader fails silently
        require "/my/base/path/" . $file;
    }
});

$loader = new UniversalClassLoader();
AnnotationRegistry::registerLoader(array($loader, "loadClass"));
2
3
4
5
6
7
8
9
10
11
12
13
14

1
$reader = new \Doctrine\Common\Annotations\AnnotationReader();
AnnotationReader::addGlobalIgnoredName('foo');
2

1
$reader = new \Doctrine\Common\Annotations\AnnotationReader();
$reader->setEnabledPhpImports(false);
2