[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Zend Framework (http://framework.zend.com/)
   4   *
   5   * @link      http://github.com/zendframework/zf2 for the canonical source repository
   6   * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
   7   * @license   http://framework.zend.com/license/new-bsd New BSD License
   8   */
   9  
  10  namespace Zend\Code\Annotation\Parser;
  11  
  12  use Doctrine\Common\Annotations\AnnotationRegistry;
  13  use Doctrine\Common\Annotations\DocParser;
  14  use Traversable;
  15  use Zend\Code\Exception;
  16  use Zend\EventManager\EventInterface;
  17  
  18  /**
  19   * A parser for docblock annotations that utilizes the annotation parser from
  20   * Doctrine\Common.
  21   *
  22   * Consumes Doctrine\Common\Annotations\DocParser, and responds to events from
  23   * AnnotationManager. If the annotation examined is in the list of classes we
  24   * are interested in, the raw annotation is passed to the DocParser in order to
  25   * retrieve the annotation object instance. Otherwise, it is skipped.
  26   */
  27  class DoctrineAnnotationParser implements ParserInterface
  28  {
  29      /**
  30       * @var array Annotation classes we support on this iteration
  31       */
  32      protected $allowedAnnotations = array();
  33  
  34      /**
  35       * @var DocParser
  36       */
  37      protected $docParser;
  38  
  39      public function __construct()
  40      {
  41          // Hack to ensure an attempt to autoload an annotation class is made
  42          AnnotationRegistry::registerLoader(function ($class) {
  43              return (bool) class_exists($class);
  44          });
  45      }
  46  
  47      /**
  48       * Set the DocParser instance
  49       *
  50       * @param  DocParser $docParser
  51       * @return DoctrineAnnotationParser
  52       */
  53      public function setDocParser(DocParser $docParser)
  54      {
  55          $this->docParser = $docParser;
  56          return $this;
  57      }
  58  
  59      /**
  60       * Retrieve the DocParser instance
  61       *
  62       * If none is registered, lazy-loads a new instance.
  63       *
  64       * @return DocParser
  65       */
  66      public function getDocParser()
  67      {
  68          if (!$this->docParser instanceof DocParser) {
  69              $this->setDocParser(new DocParser());
  70          }
  71  
  72          return $this->docParser;
  73      }
  74  
  75      /**
  76       * Handle annotation creation
  77       *
  78       * @param  EventInterface $e
  79       * @return false|\stdClass
  80       */
  81      public function onCreateAnnotation(EventInterface $e)
  82      {
  83          $annotationClass = $e->getParam('class', false);
  84          if (!$annotationClass) {
  85              return false;
  86          }
  87  
  88          if (!isset($this->allowedAnnotations[$annotationClass])) {
  89              return false;
  90          }
  91  
  92          $annotationString = $e->getParam('raw', false);
  93          if (!$annotationString) {
  94              return false;
  95          }
  96  
  97          // Annotation classes provided by the AnnotationScanner are already
  98          // resolved to fully-qualified class names. Adding the global namespace
  99          // prefix allows the Doctrine annotation parser to locate the annotation
 100          // class correctly.
 101          $annotationString = preg_replace('/^(@)/', '$1\\', $annotationString);
 102  
 103          $parser      = $this->getDocParser();
 104          $annotations = $parser->parse($annotationString);
 105          if (empty($annotations)) {
 106              return false;
 107          }
 108  
 109          $annotation = array_shift($annotations);
 110          if (!is_object($annotation)) {
 111              return false;
 112          }
 113  
 114          return $annotation;
 115      }
 116  
 117      /**
 118       * Specify an allowed annotation class
 119       *
 120       * @param  string $annotation
 121       * @return DoctrineAnnotationParser
 122       */
 123      public function registerAnnotation($annotation)
 124      {
 125          $this->allowedAnnotations[$annotation] = true;
 126          return $this;
 127      }
 128  
 129      /**
 130       * Set many allowed annotations at once
 131       *
 132       * @param  array|Traversable $annotations Array or traversable object of
 133       *         annotation class names
 134       * @throws Exception\InvalidArgumentException
 135       * @return DoctrineAnnotationParser
 136       */
 137      public function registerAnnotations($annotations)
 138      {
 139          if (!is_array($annotations) && !$annotations instanceof Traversable) {
 140              throw new Exception\InvalidArgumentException(sprintf(
 141                  '%s: expects an array or Traversable; received "%s"',
 142                  __METHOD__,
 143                  (is_object($annotations) ? get_class($annotations) : gettype($annotations))
 144              ));
 145          }
 146  
 147          foreach ($annotations as $annotation) {
 148              $this->allowedAnnotations[$annotation] = true;
 149          }
 150  
 151          return $this;
 152      }
 153  }