Chris@12: <?php
Chris@12: /**
Chris@12:  * This file is part of phpDocumentor.
Chris@12:  *
Chris@12:  * For the full copyright and license information, please view the LICENSE
Chris@12:  * file that was distributed with this source code.
Chris@12:  *
Chris@12:  * @copyright 2010-2015 Mike van Riel<mike@phpdoc.org>
Chris@12:  * @license   http://www.opensource.org/licenses/mit-license.php MIT
Chris@12:  * @link      http://phpdoc.org
Chris@12:  */
Chris@12: 
Chris@12: namespace phpDocumentor\Reflection\DocBlock;
Chris@12: 
Chris@12: use phpDocumentor\Reflection\DocBlock;
Chris@12: use Webmozart\Assert\Assert;
Chris@12: 
Chris@12: /**
Chris@12:  * Converts a DocBlock back from an object to a complete DocComment including Asterisks.
Chris@12:  */
Chris@12: class Serializer
Chris@12: {
Chris@12:     /** @var string The string to indent the comment with. */
Chris@12:     protected $indentString = ' ';
Chris@12: 
Chris@12:     /** @var int The number of times the indent string is repeated. */
Chris@12:     protected $indent = 0;
Chris@12: 
Chris@12:     /** @var bool Whether to indent the first line with the given indent amount and string. */
Chris@12:     protected $isFirstLineIndented = true;
Chris@12: 
Chris@12:     /** @var int|null The max length of a line. */
Chris@12:     protected $lineLength = null;
Chris@12: 
Chris@12:     /** @var DocBlock\Tags\Formatter A custom tag formatter. */
Chris@12:     protected $tagFormatter = null;
Chris@12: 
Chris@12:     /**
Chris@12:      * Create a Serializer instance.
Chris@12:      *
Chris@12:      * @param int $indent The number of times the indent string is repeated.
Chris@12:      * @param string   $indentString    The string to indent the comment with.
Chris@12:      * @param bool     $indentFirstLine Whether to indent the first line.
Chris@12:      * @param int|null $lineLength The max length of a line or NULL to disable line wrapping.
Chris@12:      * @param DocBlock\Tags\Formatter $tagFormatter A custom tag formatter, defaults to PassthroughFormatter.
Chris@12:      */
Chris@12:     public function __construct($indent = 0, $indentString = ' ', $indentFirstLine = true, $lineLength = null, $tagFormatter = null)
Chris@12:     {
Chris@12:         Assert::integer($indent);
Chris@12:         Assert::string($indentString);
Chris@12:         Assert::boolean($indentFirstLine);
Chris@12:         Assert::nullOrInteger($lineLength);
Chris@12:         Assert::nullOrIsInstanceOf($tagFormatter, 'phpDocumentor\Reflection\DocBlock\Tags\Formatter');
Chris@12: 
Chris@12:         $this->indent = $indent;
Chris@12:         $this->indentString = $indentString;
Chris@12:         $this->isFirstLineIndented = $indentFirstLine;
Chris@12:         $this->lineLength = $lineLength;
Chris@12:         $this->tagFormatter = $tagFormatter ?: new DocBlock\Tags\Formatter\PassthroughFormatter();
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Generate a DocBlock comment.
Chris@12:      *
Chris@12:      * @param DocBlock $docblock The DocBlock to serialize.
Chris@12:      *
Chris@12:      * @return string The serialized doc block.
Chris@12:      */
Chris@12:     public function getDocComment(DocBlock $docblock)
Chris@12:     {
Chris@12:         $indent = str_repeat($this->indentString, $this->indent);
Chris@12:         $firstIndent = $this->isFirstLineIndented ? $indent : '';
Chris@12:         // 3 === strlen(' * ')
Chris@12:         $wrapLength = $this->lineLength ? $this->lineLength - strlen($indent) - 3 : null;
Chris@12: 
Chris@12:         $text = $this->removeTrailingSpaces(
Chris@12:             $indent,
Chris@12:             $this->addAsterisksForEachLine(
Chris@12:                 $indent,
Chris@12:                 $this->getSummaryAndDescriptionTextBlock($docblock, $wrapLength)
Chris@12:             )
Chris@12:         );
Chris@12: 
Chris@12:         $comment = "{$firstIndent}/**\n";
Chris@12:         if ($text) {
Chris@12:             $comment .= "{$indent} * {$text}\n";
Chris@12:             $comment .= "{$indent} *\n";
Chris@12:         }
Chris@12: 
Chris@12:         $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
Chris@12:         $comment .= $indent . ' */';
Chris@12: 
Chris@12:         return $comment;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @param $indent
Chris@12:      * @param $text
Chris@12:      * @return mixed
Chris@12:      */
Chris@12:     private function removeTrailingSpaces($indent, $text)
Chris@12:     {
Chris@12:         return str_replace("\n{$indent} * \n", "\n{$indent} *\n", $text);
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @param $indent
Chris@12:      * @param $text
Chris@12:      * @return mixed
Chris@12:      */
Chris@12:     private function addAsterisksForEachLine($indent, $text)
Chris@12:     {
Chris@12:         return str_replace("\n", "\n{$indent} * ", $text);
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @param DocBlock $docblock
Chris@12:      * @param $wrapLength
Chris@12:      * @return string
Chris@12:      */
Chris@12:     private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength)
Chris@12:     {
Chris@12:         $text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription()
Chris@12:                 : '');
Chris@12:         if ($wrapLength !== null) {
Chris@12:             $text = wordwrap($text, $wrapLength);
Chris@12:             return $text;
Chris@12:         }
Chris@12: 
Chris@12:         return $text;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @param DocBlock $docblock
Chris@12:      * @param $wrapLength
Chris@12:      * @param $indent
Chris@12:      * @param $comment
Chris@12:      * @return string
Chris@12:      */
Chris@12:     private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment)
Chris@12:     {
Chris@12:         foreach ($docblock->getTags() as $tag) {
Chris@12:             $tagText = $this->tagFormatter->format($tag);
Chris@12:             if ($wrapLength !== null) {
Chris@12:                 $tagText = wordwrap($tagText, $wrapLength);
Chris@12:             }
Chris@12: 
Chris@12:             $tagText = str_replace("\n", "\n{$indent} * ", $tagText);
Chris@12: 
Chris@12:             $comment .= "{$indent} * {$tagText}\n";
Chris@12:         }
Chris@12: 
Chris@12:         return $comment;
Chris@12:     }
Chris@12: }