Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
156 lines (113 sloc) 4.66 KB
The Doctrine Annotations library was born from a need in the [Doctrine2 ORM](
to allow the mapping information to be specified inside the doc-blocks of classes,
properties and methods. The library is independent and can be used in your own libraries
to implement doc block annotations.
++ Setup and Configuration
To use the annotations library is simple, you just need to create a new `AnnotationReader`
$reader = new \Doctrine\Common\Annotations\AnnotationReader();
The `AnnotationReader` class takes two optional constructor arguments:
* **Doctrine\Common\Cache\Cache $cache** - The cache driver to use for caching read annotations.
* **Doctrine\Common\Annotations\Parser $parser** - The annotations parser class to use to parse the doc-block annotations.
So for more control you can do the following:
$reader = new \Doctrine\Common\Annotations\AnnotationReader(
new \Doctrine\Common\Cache\ApcCache(),
new \Doctrine\Common\Annotations\Parser()
+++ Autoload Annotation Classes
If you want Doctrine to try and autoload annotation classes with `class_exists()` then you
need to configure the `AnnotationReader` instance to do so:
If this is set to false then all annotation classes must be previously manually loaded.
+++ Default Namespace
If you don't want to specify the fully qualified class name you can set the default
annotation namespace using the `setDefaultAnnotationNamespace()` method. The following
is an example where we specify the fully qualified class name for the annotation:
/** @MyCompany\Annotations\Foo */
class Test
To shorten the above code you can configure the default namespace to be `MyCompany\Annotations`:
Now it can look something like:
/** @Foo */
class Test
A little nicer looking!
+++ Namespace Aliases
Again to save you from having to specify the fully qualified class name you can set an alias
for a namespace of annotation classes:
$reader->setAnnotationNamespaceAlias('MyCompany\Annotations', 'my');
So now you could do something like this:
/** @my:Foo */
class Test
Again, a bit nicer looking than the fully qualified class name!
+++ Annotation Creation
If you want to customize the creation process of the annotation class instances then you
have two options, you can sub-class the `Doctrine\Common\Annotations\Parser` class and
override the `newAnnotation()` method:
class MyParser extends Parser
protected function newAnnotation($name, array $values)
return new $name($values);
The other option is to use the `setAnnotationCreationFunction()` method to specify a closure
to execute:
$reader->setAnnotationCreationFunction(function($name, array $values) {
return new $name($values);
++ Usage
Using the library API is simple. First lets define some annotation classes:
namespace MyCompany\Annotations;
class Foo extends \Doctrine\Common\Annotations\Annotation
public $bar;
class Bar
public $foo;
Now to use the annotations you would just need to do the following:
* @Foo(bar="test")
* @Bar(foo="test")
class User
Now we can write a script to get the annotations above:
$reflClass = new ReflectionClass('User');
$classAnnotations = $reader->getClassAnnotations($reflClass);
echo $classAnnotations['MyCompany\Annotations\Foo']->bar; // prints foo
echo $classAnnotations['MyCompany\Annotations\Foo']->foo; // prints bar
You have a complete API for retrieving annotation class instances from a class, property
or method docblock:
* getClassAnnotations(ReflectionClass $class)
* getClassAnnotation(ReflectionClass $class, $annotation)
* getPropertyAnnotations(ReflectionProperty $property)
* getPropertyAnnotation(ReflectionProperty $property, $annotation)
* getMethodAnnotations(ReflectionMethod $method)
* getMethodAnnotation(ReflectionMethod $method, $annotation)
> The AnnotationReader works and caches under the assumption that all annotations of a
> doc-block are processed at once. That means that annotation classes that do not exist and
> aren't loaded and cannot be autoloaded (using setAutoloadAnnotationClasses()) would never
> be visible and not accessible if a cache is used unless the cache is cleared and the
> annotations requested again, this time with all annotations defined.
Jump to Line
Something went wrong with that request. Please try again.