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