interface/modules/zend_modules/library/Zend/Code/Generator/DocBlockGenerator.php

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