1Introduction
2============
3
4Doctrine Annotations offers to implement custom annotation
5functionality for PHP classes.
6
7.. code-block:: php
8
9    class Foo
10    {
11        /**
12         * @MyAnnotation(myProperty="value")
13         */
14        private $bar;
15    }
16
17Annotations aren't implemented in PHP itself which is why
18this component offers a way to use the PHP doc-blocks as a
19place for the well known annotation syntax using the
20``@`` char.
21
22Annotations in Doctrine are used for the ORM
23configuration to build the class mapping, but it can
24be used in other projects for other purposes too.
25
26Installation
27============
28
29You can install the Annotation component with composer:
30
31.. code-block::
32
33    $ composer require doctrine/annotations
34
35Create an annotation class
36==========================
37
38An annotation class is a representation of the later
39used annotation configuration in classes. The annotation
40class of the previous example looks like this:
41
42.. code-block:: php
43
44    /**
45     * @Annotation
46     */
47    final class MyAnnotation
48    {
49        public $myProperty;
50    }
51
52The annotation class is declared as an annotation by
53``@Annotation``.
54
55:ref:`Read more about custom annotations. <custom>`
56
57Reading annotations
58===================
59
60The access to the annotations happens by reflection of the class
61containing them. There are multiple reader-classes implementing the
62``Doctrine\Common\Annotations\Reader`` interface, that can
63access the annotations of a class. A common one is
64``Doctrine\Common\Annotations\AnnotationReader``:
65
66.. code-block:: php
67
68    $reflectionClass = new ReflectionClass(Foo::class);
69    $property = $reflectionClass->getProperty('bar');
70
71    $reader = new AnnotationReader();
72    $myAnnotation = $reader->getPropertyAnnotation(
73        $property,
74        MyAnnotation::class
75    );
76
77    echo $myAnnotation->myProperty; // result: "value"
78
79A reader has multiple methods to access the annotations
80of a class.
81
82:ref:`Read more about handling annotations. <annotations>`
83
84IDE Support
85-----------
86
87Some IDEs already provide support for annotations:
88
89- Eclipse via the `Symfony2 Plugin <http://symfony.dubture.com/>`_
90- PHPStorm via the `PHP Annotations Plugin <http://plugins.jetbrains.com/plugin/7320>`_ or the `Symfony2 Plugin <http://plugins.jetbrains.com/plugin/7219>`_
91
92.. _Read more about handling annotations.: annotations
93.. _Read more about custom annotations.: custom
94