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