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