AnnotationReader.php 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  1. <?php
  2. /*
  3. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  4. * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  5. * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  6. * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  7. * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  8. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  9. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10. * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11. * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12. * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13. * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. *
  15. * This software consists of voluntary contributions made by many individuals
  16. * and is licensed under the LGPL. For more information, see
  17. * <http://www.doctrine-project.org>.
  18. */
  19. namespace Doctrine\Common\Annotations;
  20. use Doctrine\Common\Annotations\Annotation\IgnoreAnnotation;
  21. use Doctrine\Common\Annotations\Annotation\Target;
  22. use Closure;
  23. use ReflectionClass;
  24. use ReflectionMethod;
  25. use ReflectionProperty;
  26. /**
  27. * A reader for docblock annotations.
  28. *
  29. * @author Benjamin Eberlei <kontakt@beberlei.de>
  30. * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
  31. * @author Jonathan Wage <jonwage@gmail.com>
  32. * @author Roman Borschel <roman@code-factory.org>
  33. * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  34. */
  35. final class AnnotationReader implements Reader
  36. {
  37. /**
  38. * Global map for imports.
  39. *
  40. * @var array
  41. */
  42. private static $globalImports = array(
  43. 'ignoreannotation' => 'Doctrine\Common\Annotations\Annotation\IgnoreAnnotation',
  44. );
  45. /**
  46. * A list with annotations that are not causing exceptions when not resolved to an annotation class.
  47. *
  48. * The names are case sensitive.
  49. *
  50. * @var array
  51. */
  52. private static $globalIgnoredNames = array(
  53. 'access'=> true, 'author'=> true, 'copyright'=> true, 'deprecated'=> true,
  54. 'example'=> true, 'ignore'=> true, 'internal'=> true, 'link'=> true, 'see'=> true,
  55. 'since'=> true, 'tutorial'=> true, 'version'=> true, 'package'=> true,
  56. 'subpackage'=> true, 'name'=> true, 'global'=> true, 'param'=> true,
  57. 'return'=> true, 'staticvar'=> true, 'category'=> true, 'staticVar'=> true,
  58. 'static'=> true, 'var'=> true, 'throws'=> true, 'inheritdoc'=> true,
  59. 'inheritDoc'=> true, 'license'=> true, 'todo'=> true, 'deprecated'=> true,
  60. 'deprec'=> true, 'author'=> true, 'property' => true, 'method' => true,
  61. 'abstract'=> true, 'exception'=> true, 'magic' => true, 'api' => true,
  62. 'final'=> true, 'filesource'=> true, 'throw' => true, 'uses' => true,
  63. 'usedby'=> true, 'private' => true, 'Annotation' => true, 'override' => true,
  64. 'codeCoverageIgnore' => true, 'codeCoverageIgnoreStart' => true, 'codeCoverageIgnoreEnd' => true,
  65. 'Required' => true, 'Attribute' => true, 'Attributes' => true,
  66. 'Target' => true, 'SuppressWarnings' => true,
  67. );
  68. /**
  69. * Add a new annotation to the globally ignored annotation names with regard to exception handling.
  70. *
  71. * @param string $name
  72. */
  73. static public function addGlobalIgnoredName($name)
  74. {
  75. self::$globalIgnoredNames[$name] = true;
  76. }
  77. /**
  78. * Annotations Parser
  79. *
  80. * @var Doctrine\Common\Annotations\DocParser
  81. */
  82. private $parser;
  83. /**
  84. * Annotations Parser used to collect parsing metadata
  85. *
  86. * @var Doctrine\Common\Annotations\DocParser
  87. */
  88. private $preParser;
  89. /**
  90. * PHP Parser used to collect imports.
  91. *
  92. * @var Doctrine\Common\Annotations\PhpParser
  93. */
  94. private $phpParser;
  95. /**
  96. * In-memory cache mechanism to store imported annotations per class.
  97. *
  98. * @var array
  99. */
  100. private $imports = array();
  101. /**
  102. * In-memory cache mechanism to store ignored annotations per class.
  103. *
  104. * @var array
  105. */
  106. private $ignoredAnnotationNames = array();
  107. /**
  108. * Constructor.
  109. *
  110. * Initializes a new AnnotationReader.
  111. */
  112. public function __construct()
  113. {
  114. AnnotationRegistry::registerFile(__DIR__ . '/Annotation/IgnoreAnnotation.php');
  115. $this->parser = new DocParser;
  116. $this->preParser = new DocParser;
  117. $this->preParser->setImports(self::$globalImports);
  118. $this->preParser->setIgnoreNotImportedAnnotations(true);
  119. $this->phpParser = new PhpParser;
  120. }
  121. /**
  122. * Gets the annotations applied to a class.
  123. *
  124. * @param ReflectionClass $class The ReflectionClass of the class from which
  125. * the class annotations should be read.
  126. * @return array An array of Annotations.
  127. */
  128. public function getClassAnnotations(ReflectionClass $class)
  129. {
  130. $this->parser->setTarget(Target::TARGET_CLASS);
  131. $this->parser->setImports($this->getImports($class));
  132. $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  133. return $this->parser->parse($class->getDocComment(), 'class ' . $class->getName());
  134. }
  135. /**
  136. * Gets a class annotation.
  137. *
  138. * @param ReflectionClass $class The ReflectionClass of the class from which
  139. * the class annotations should be read.
  140. * @param string $annotationName The name of the annotation.
  141. * @return The Annotation or NULL, if the requested annotation does not exist.
  142. */
  143. public function getClassAnnotation(ReflectionClass $class, $annotationName)
  144. {
  145. $annotations = $this->getClassAnnotations($class);
  146. foreach ($annotations as $annotation) {
  147. if ($annotation instanceof $annotationName) {
  148. return $annotation;
  149. }
  150. }
  151. return null;
  152. }
  153. /**
  154. * Gets the annotations applied to a property.
  155. *
  156. * @param ReflectionProperty $property The ReflectionProperty of the property
  157. * from which the annotations should be read.
  158. * @return array An array of Annotations.
  159. */
  160. public function getPropertyAnnotations(ReflectionProperty $property)
  161. {
  162. $class = $property->getDeclaringClass();
  163. $context = 'property ' . $class->getName() . "::\$" . $property->getName();
  164. $this->parser->setTarget(Target::TARGET_PROPERTY);
  165. $this->parser->setImports($this->getImports($class));
  166. $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  167. return $this->parser->parse($property->getDocComment(), $context);
  168. }
  169. /**
  170. * Gets a property annotation.
  171. *
  172. * @param ReflectionProperty $property
  173. * @param string $annotationName The name of the annotation.
  174. * @return The Annotation or NULL, if the requested annotation does not exist.
  175. */
  176. public function getPropertyAnnotation(ReflectionProperty $property, $annotationName)
  177. {
  178. $annotations = $this->getPropertyAnnotations($property);
  179. foreach ($annotations as $annotation) {
  180. if ($annotation instanceof $annotationName) {
  181. return $annotation;
  182. }
  183. }
  184. return null;
  185. }
  186. /**
  187. * Gets the annotations applied to a method.
  188. *
  189. * @param ReflectionMethod $property The ReflectionMethod of the method from which
  190. * the annotations should be read.
  191. * @return array An array of Annotations.
  192. */
  193. public function getMethodAnnotations(ReflectionMethod $method)
  194. {
  195. $class = $method->getDeclaringClass();
  196. $context = 'method ' . $class->getName() . '::' . $method->getName() . '()';
  197. $this->parser->setTarget(Target::TARGET_METHOD);
  198. $this->parser->setImports($this->getImports($class));
  199. $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  200. return $this->parser->parse($method->getDocComment(), $context);
  201. }
  202. /**
  203. * Gets a method annotation.
  204. *
  205. * @param ReflectionMethod $method
  206. * @param string $annotationName The name of the annotation.
  207. * @return The Annotation or NULL, if the requested annotation does not exist.
  208. */
  209. public function getMethodAnnotation(ReflectionMethod $method, $annotationName)
  210. {
  211. $annotations = $this->getMethodAnnotations($method);
  212. foreach ($annotations as $annotation) {
  213. if ($annotation instanceof $annotationName) {
  214. return $annotation;
  215. }
  216. }
  217. return null;
  218. }
  219. /**
  220. * Returns the ignored annotations for the given class.
  221. *
  222. * @param ReflectionClass $class
  223. * @return array
  224. */
  225. private function getIgnoredAnnotationNames(ReflectionClass $class)
  226. {
  227. if (isset($this->ignoredAnnotationNames[$name = $class->getName()])) {
  228. return $this->ignoredAnnotationNames[$name];
  229. }
  230. $this->collectParsingMetadata($class);
  231. return $this->ignoredAnnotationNames[$name];
  232. }
  233. private function getImports(ReflectionClass $class)
  234. {
  235. if (isset($this->imports[$name = $class->getName()])) {
  236. return $this->imports[$name];
  237. }
  238. $this->collectParsingMetadata($class);
  239. return $this->imports[$name];
  240. }
  241. /**
  242. * Collects parsing metadata for a given class
  243. *
  244. * @param ReflectionClass $class
  245. */
  246. private function collectParsingMetadata(ReflectionClass $class)
  247. {
  248. $ignoredAnnotationNames = self::$globalIgnoredNames;
  249. $annotations = $this->preParser->parse($class->getDocComment(), 'class '.$class->name);
  250. foreach ($annotations as $annotation) {
  251. if ($annotation instanceof IgnoreAnnotation) {
  252. foreach ($annotation->names AS $annot) {
  253. $ignoredAnnotationNames[$annot] = true;
  254. }
  255. }
  256. }
  257. $name = $class->getName();
  258. $this->imports[$name] = array_merge(
  259. self::$globalImports,
  260. $this->phpParser->parseClass($class),
  261. array('__NAMESPACE__' => $class->getNamespaceName())
  262. );
  263. $this->ignoredAnnotationNames[$name] = $ignoredAnnotationNames;
  264. }
  265. }