[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\Reflection;
  11  
  12  use Reflector;
  13  use Zend\Code\Reflection\DocBlock\Tag\TagInterface as DocBlockTagInterface;
  14  use Zend\Code\Reflection\DocBlock\TagManager as DocBlockTagManager;
  15  use Zend\Code\Scanner\DocBlockScanner;
  16  
  17  use function count;
  18  use function get_class;
  19  use function is_string;
  20  use function ltrim;
  21  use function method_exists;
  22  use function preg_replace;
  23  use function sprintf;
  24  use function substr_count;
  25  
  26  class DocBlockReflection implements ReflectionInterface
  27  {
  28      /**
  29       * @var Reflector
  30       */
  31      protected $reflector;
  32  
  33      /**
  34       * @var string
  35       */
  36      protected $docComment;
  37  
  38      /**
  39       * @var DocBlockTagManager
  40       */
  41      protected $tagManager;
  42  
  43      /**
  44       * @var int
  45       */
  46      protected $startLine;
  47  
  48      /**
  49       * @var int
  50       */
  51      protected $endLine;
  52  
  53      /**
  54       * @var string
  55       */
  56      protected $cleanDocComment;
  57  
  58      /**
  59       * @var string
  60       */
  61      protected $longDescription;
  62  
  63      /**
  64       * @var string
  65       */
  66      protected $shortDescription;
  67  
  68      /**
  69       * @var array
  70       */
  71      protected $tags = [];
  72  
  73      /**
  74       * @var bool
  75       */
  76      protected $isReflected = false;
  77  
  78      /**
  79       * Export reflection
  80       *
  81       * Required by the Reflector interface.
  82       *
  83       * @todo   What should this do?
  84       * @return void
  85       */
  86      public static function export()
  87      {
  88      }
  89  
  90      /**
  91       * @param  Reflector|string $commentOrReflector
  92       * @param  null|DocBlockTagManager $tagManager
  93       * @throws Exception\InvalidArgumentException
  94       */
  95      public function __construct($commentOrReflector, DocBlockTagManager $tagManager = null)
  96      {
  97          if (! $tagManager) {
  98              $tagManager = new DocBlockTagManager();
  99              $tagManager->initializeDefaultTags();
 100          }
 101          $this->tagManager = $tagManager;
 102  
 103          if ($commentOrReflector instanceof Reflector) {
 104              $this->reflector = $commentOrReflector;
 105              if (! method_exists($commentOrReflector, 'getDocComment')) {
 106                  throw new Exception\InvalidArgumentException('Reflector must contain method "getDocComment"');
 107              }
 108              /* @var MethodReflection $commentOrReflector */
 109              $this->docComment = $commentOrReflector->getDocComment();
 110  
 111              // determine line numbers
 112              $lineCount       = substr_count($this->docComment, "\n");
 113              $this->startLine = $this->reflector->getStartLine() - $lineCount - 1;
 114              $this->endLine   = $this->reflector->getStartLine() - 1;
 115          } elseif (is_string($commentOrReflector)) {
 116              $this->docComment = $commentOrReflector;
 117          } else {
 118              throw new Exception\InvalidArgumentException(sprintf(
 119                  '%s must have a (string) DocComment or a Reflector in the constructor',
 120                  get_class($this)
 121              ));
 122          }
 123  
 124          if ($this->docComment == '') {
 125              throw new Exception\InvalidArgumentException('DocComment cannot be empty');
 126          }
 127  
 128          $this->reflect();
 129      }
 130  
 131      /**
 132       * Retrieve contents of DocBlock
 133       *
 134       * @return string
 135       */
 136      public function getContents()
 137      {
 138          $this->reflect();
 139  
 140          return $this->cleanDocComment;
 141      }
 142  
 143      /**
 144       * Get start line (position) of DocBlock
 145       *
 146       * @return int
 147       */
 148      public function getStartLine()
 149      {
 150          $this->reflect();
 151  
 152          return $this->startLine;
 153      }
 154  
 155      /**
 156       * Get last line (position) of DocBlock
 157       *
 158       * @return int
 159       */
 160      public function getEndLine()
 161      {
 162          $this->reflect();
 163  
 164          return $this->endLine;
 165      }
 166  
 167      /**
 168       * Get DocBlock short description
 169       *
 170       * @return string
 171       */
 172      public function getShortDescription()
 173      {
 174          $this->reflect();
 175  
 176          return $this->shortDescription;
 177      }
 178  
 179      /**
 180       * Get DocBlock long description
 181       *
 182       * @return string
 183       */
 184      public function getLongDescription()
 185      {
 186          $this->reflect();
 187  
 188          return $this->longDescription;
 189      }
 190  
 191      /**
 192       * Does the DocBlock contain the given annotation tag?
 193       *
 194       * @param  string $name
 195       * @return bool
 196       */
 197      public function hasTag($name)
 198      {
 199          $this->reflect();
 200          foreach ($this->tags as $tag) {
 201              if ($tag->getName() == $name) {
 202                  return true;
 203              }
 204          }
 205  
 206          return false;
 207      }
 208  
 209      /**
 210       * Retrieve the given DocBlock tag
 211       *
 212       * @param  string $name
 213       * @return DocBlockTagInterface|false
 214       */
 215      public function getTag($name)
 216      {
 217          $this->reflect();
 218          foreach ($this->tags as $tag) {
 219              if ($tag->getName() == $name) {
 220                  return $tag;
 221              }
 222          }
 223  
 224          return false;
 225      }
 226  
 227      /**
 228       * Get all DocBlock annotation tags
 229       *
 230       * @param  string $filter
 231       * @return DocBlockTagInterface[]
 232       */
 233      public function getTags($filter = null)
 234      {
 235          $this->reflect();
 236          if ($filter === null || ! is_string($filter)) {
 237              return $this->tags;
 238          }
 239  
 240          $returnTags = [];
 241          foreach ($this->tags as $tag) {
 242              if ($tag->getName() == $filter) {
 243                  $returnTags[] = $tag;
 244              }
 245          }
 246  
 247          return $returnTags;
 248      }
 249  
 250      /**
 251       * Parse the DocBlock
 252       *
 253       * @return void
 254       */
 255      protected function reflect()
 256      {
 257          if ($this->isReflected) {
 258              return;
 259          }
 260  
 261          $docComment = preg_replace('#[ ]{0,1}\*/$#', '', $this->docComment);
 262  
 263          // create a clean docComment
 264          $this->cleanDocComment = preg_replace("#[ \t]*(?:/\*\*|\*/|\*)[ ]{0,1}(.*)?#", '$1', $docComment);
 265  
 266          // @todo should be changed to remove first and last empty line
 267          $this->cleanDocComment = ltrim($this->cleanDocComment, "\r\n");
 268  
 269          $scanner                = new DocBlockScanner($docComment);
 270          $this->shortDescription = ltrim($scanner->getShortDescription());
 271          $this->longDescription  = ltrim($scanner->getLongDescription());
 272  
 273          foreach ($scanner->getTags() as $tag) {
 274              $this->tags[] = $this->tagManager->createTag(ltrim($tag['name'], '@'), ltrim($tag['value']));
 275          }
 276  
 277          $this->isReflected = true;
 278      }
 279  
 280      /**
 281       * @return string
 282       */
 283      public function toString()
 284      {
 285          $str = 'DocBlock [ /* DocBlock */ ] {' . "\n\n";
 286          $str .= '  - Tags [' . count($this->tags) . '] {' . "\n";
 287  
 288          foreach ($this->tags as $tag) {
 289              $str .= '    ' . $tag;
 290          }
 291  
 292          $str .= '  }' . "\n";
 293          $str .= '}' . "\n";
 294  
 295          return $str;
 296      }
 297  
 298      /**
 299       * Serialize to string
 300       *
 301       * Required by the Reflector interface
 302       *
 303       * @return string
 304       */
 305      public function __toString()
 306      {
 307          return $this->toString();
 308      }
 309  }