[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\Generator;
  11  
  12  use Zend\Code\Generator\DocBlock\Tag;
  13  use Zend\Code\Generator\DocBlock\Tag\TagInterface;
  14  use Zend\Code\Generator\DocBlock\TagManager;
  15  use Zend\Code\Reflection\DocBlockReflection;
  16  
  17  use function explode;
  18  use function is_array;
  19  use function sprintf;
  20  use function str_replace;
  21  use function strtolower;
  22  use function trim;
  23  use function wordwrap;
  24  
  25  class DocBlockGenerator extends AbstractGenerator
  26  {
  27      /**
  28       * @var string
  29       */
  30      protected $shortDescription;
  31  
  32      /**
  33       * @var string
  34       */
  35      protected $longDescription;
  36  
  37      /**
  38       * @var array
  39       */
  40      protected $tags = [];
  41  
  42      /**
  43       * @var string
  44       */
  45      protected $indentation = '';
  46  
  47      /**
  48       * @var bool
  49       */
  50      protected $wordwrap = true;
  51  
  52      /**
  53       * @var TagManager
  54       */
  55      protected static $tagManager;
  56  
  57      /**
  58       * Build a DocBlock generator object from a reflection object
  59       *
  60       * @param  DocBlockReflection $reflectionDocBlock
  61       * @return DocBlockGenerator
  62       */
  63      public static function fromReflection(DocBlockReflection $reflectionDocBlock)
  64      {
  65          $docBlock = new static();
  66  
  67          $docBlock->setSourceContent($reflectionDocBlock->getContents());
  68          $docBlock->setSourceDirty(false);
  69  
  70          $docBlock->setShortDescription($reflectionDocBlock->getShortDescription());
  71          $docBlock->setLongDescription($reflectionDocBlock->getLongDescription());
  72  
  73          foreach ($reflectionDocBlock->getTags() as $tag) {
  74              $docBlock->setTag(self::getTagManager()->createTagFromReflection($tag));
  75          }
  76  
  77          return $docBlock;
  78      }
  79  
  80      /**
  81       * Generate from array
  82       *
  83       * @configkey shortdescription string The short description for this doc block
  84       * @configkey longdescription  string The long description for this doc block
  85       * @configkey tags             array
  86       *
  87       * @throws Exception\InvalidArgumentException
  88       * @param  array $array
  89       * @return DocBlockGenerator
  90       */
  91      public static function fromArray(array $array)
  92      {
  93          $docBlock = new static();
  94  
  95          foreach ($array as $name => $value) {
  96              // normalize key
  97              switch (strtolower(str_replace(['.', '-', '_'], '', $name))) {
  98                  case 'shortdescription':
  99                      $docBlock->setShortDescription($value);
 100                      break;
 101                  case 'longdescription':
 102                      $docBlock->setLongDescription($value);
 103                      break;
 104                  case 'tags':
 105                      $docBlock->setTags($value);
 106                      break;
 107              }
 108          }
 109  
 110          return $docBlock;
 111      }
 112  
 113      /**
 114       * @return TagManager
 115       */
 116      protected static function getTagManager()
 117      {
 118          if (! isset(static::$tagManager)) {
 119              static::$tagManager = new TagManager();
 120              static::$tagManager->initializeDefaultTags();
 121          }
 122          return static::$tagManager;
 123      }
 124  
 125      /**
 126       * @param  string $shortDescription
 127       * @param  string $longDescription
 128       * @param  array $tags
 129       */
 130      public function __construct($shortDescription = null, $longDescription = null, array $tags = [])
 131      {
 132          if ($shortDescription) {
 133              $this->setShortDescription($shortDescription);
 134          }
 135          if ($longDescription) {
 136              $this->setLongDescription($longDescription);
 137          }
 138          if (is_array($tags) && $tags) {
 139              $this->setTags($tags);
 140          }
 141      }
 142  
 143      /**
 144       * @param  string $shortDescription
 145       * @return DocBlockGenerator
 146       */
 147      public function setShortDescription($shortDescription)
 148      {
 149          $this->shortDescription = $shortDescription;
 150          return $this;
 151      }
 152  
 153      /**
 154       * @return string
 155       */
 156      public function getShortDescription()
 157      {
 158          return $this->shortDescription;
 159      }
 160  
 161      /**
 162       * @param  string $longDescription
 163       * @return DocBlockGenerator
 164       */
 165      public function setLongDescription($longDescription)
 166      {
 167          $this->longDescription = $longDescription;
 168          return $this;
 169      }
 170  
 171      /**
 172       * @return string
 173       */
 174      public function getLongDescription()
 175      {
 176          return $this->longDescription;
 177      }
 178  
 179      /**
 180       * @param  array $tags
 181       * @return DocBlockGenerator
 182       */
 183      public function setTags(array $tags)
 184      {
 185          foreach ($tags as $tag) {
 186              $this->setTag($tag);
 187          }
 188  
 189          return $this;
 190      }
 191  
 192      /**
 193       * @param array|TagInterface $tag
 194       * @throws Exception\InvalidArgumentException
 195       * @return DocBlockGenerator
 196       */
 197      public function setTag($tag)
 198      {
 199          if (is_array($tag)) {
 200              // use deprecated Tag class for backward compatibility to old array-keys
 201              $genericTag = new Tag();
 202              $genericTag->setOptions($tag);
 203              $tag = $genericTag;
 204          } elseif (! $tag instanceof TagInterface) {
 205              throw new Exception\InvalidArgumentException(sprintf(
 206                  '%s expects either an array of method options or an instance of %s\DocBlock\Tag\TagInterface',
 207                  __METHOD__,
 208                  __NAMESPACE__
 209              ));
 210          }
 211  
 212          $this->tags[] = $tag;
 213          return $this;
 214      }
 215  
 216      /**
 217       * @return TagInterface[]
 218       */
 219      public function getTags()
 220      {
 221          return $this->tags;
 222      }
 223  
 224      /**
 225       * @param bool $value
 226       * @return DocBlockGenerator
 227       */
 228      public function setWordWrap($value)
 229      {
 230          $this->wordwrap = (bool) $value;
 231          return $this;
 232      }
 233  
 234      /**
 235       * @return bool
 236       */
 237      public function getWordWrap()
 238      {
 239          return $this->wordwrap;
 240      }
 241  
 242      /**
 243       * @return string
 244       */
 245      public function generate()
 246      {
 247          if (! $this->isSourceDirty()) {
 248              return $this->docCommentize(trim($this->getSourceContent()));
 249          }
 250  
 251          $output = '';
 252          if (null !== ($sd = $this->getShortDescription())) {
 253              $output .= $sd . self::LINE_FEED . self::LINE_FEED;
 254          }
 255          if (null !== ($ld = $this->getLongDescription())) {
 256              $output .= $ld . self::LINE_FEED . self::LINE_FEED;
 257          }
 258  
 259          /* @var $tag GeneratorInterface */
 260          foreach ($this->getTags() as $tag) {
 261              $output .= $tag->generate() . self::LINE_FEED;
 262          }
 263  
 264          return $this->docCommentize(trim($output));
 265      }
 266  
 267      /**
 268       * @param  string $content
 269       * @return string
 270       */
 271      protected function docCommentize($content)
 272      {
 273          $indent  = $this->getIndentation();
 274          $output  = $indent . '/**' . self::LINE_FEED;
 275          $content = $this->getWordWrap() == true ? wordwrap($content, 80, self::LINE_FEED) : $content;
 276          $lines   = explode(self::LINE_FEED, $content);
 277          foreach ($lines as $line) {
 278              $output .= $indent . ' *';
 279              if ($line) {
 280                  $output .= ' ' . $line;
 281              }
 282              $output .= self::LINE_FEED;
 283          }
 284          $output .= $indent . ' */' . self::LINE_FEED;
 285  
 286          return $output;
 287      }
 288  }