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;
Chris@12: 
Chris@12: use phpDocumentor\Reflection\DocBlock\Tag;
Chris@12: use Webmozart\Assert\Assert;
Chris@12: 
Chris@12: final class DocBlock
Chris@12: {
Chris@12:     /** @var string The opening line for this docblock. */
Chris@12:     private $summary = '';
Chris@12: 
Chris@12:     /** @var DocBlock\Description The actual description for this docblock. */
Chris@12:     private $description = null;
Chris@12: 
Chris@12:     /** @var Tag[] An array containing all the tags in this docblock; except inline. */
Chris@12:     private $tags = [];
Chris@12: 
Chris@12:     /** @var Types\Context Information about the context of this DocBlock. */
Chris@12:     private $context = null;
Chris@12: 
Chris@12:     /** @var Location Information about the location of this DocBlock. */
Chris@12:     private $location = null;
Chris@12: 
Chris@12:     /** @var bool Is this DocBlock (the start of) a template? */
Chris@12:     private $isTemplateStart = false;
Chris@12: 
Chris@12:     /** @var bool Does this DocBlock signify the end of a DocBlock template? */
Chris@12:     private $isTemplateEnd = false;
Chris@12: 
Chris@12:     /**
Chris@12:      * @param string $summary
Chris@12:      * @param DocBlock\Description $description
Chris@12:      * @param DocBlock\Tag[] $tags
Chris@12:      * @param Types\Context $context The context in which the DocBlock occurs.
Chris@12:      * @param Location $location The location within the file that this DocBlock occurs in.
Chris@12:      * @param bool $isTemplateStart
Chris@12:      * @param bool $isTemplateEnd
Chris@12:      */
Chris@12:     public function __construct(
Chris@12:         $summary = '',
Chris@12:         DocBlock\Description $description = null,
Chris@12:         array $tags = [],
Chris@12:         Types\Context $context = null,
Chris@12:         Location $location = null,
Chris@12:         $isTemplateStart = false,
Chris@12:         $isTemplateEnd = false
Chris@12:     ) {
Chris@12:         Assert::string($summary);
Chris@12:         Assert::boolean($isTemplateStart);
Chris@12:         Assert::boolean($isTemplateEnd);
Chris@12:         Assert::allIsInstanceOf($tags, Tag::class);
Chris@12: 
Chris@12:         $this->summary = $summary;
Chris@12:         $this->description = $description ?: new DocBlock\Description('');
Chris@12:         foreach ($tags as $tag) {
Chris@12:             $this->addTag($tag);
Chris@12:         }
Chris@12: 
Chris@12:         $this->context = $context;
Chris@12:         $this->location = $location;
Chris@12: 
Chris@12:         $this->isTemplateEnd = $isTemplateEnd;
Chris@12:         $this->isTemplateStart = $isTemplateStart;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @return string
Chris@12:      */
Chris@12:     public function getSummary()
Chris@12:     {
Chris@12:         return $this->summary;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * @return DocBlock\Description
Chris@12:      */
Chris@12:     public function getDescription()
Chris@12:     {
Chris@12:         return $this->description;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns the current context.
Chris@12:      *
Chris@12:      * @return Types\Context
Chris@12:      */
Chris@12:     public function getContext()
Chris@12:     {
Chris@12:         return $this->context;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns the current location.
Chris@12:      *
Chris@12:      * @return Location
Chris@12:      */
Chris@12:     public function getLocation()
Chris@12:     {
Chris@12:         return $this->location;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns whether this DocBlock is the start of a Template section.
Chris@12:      *
Chris@12:      * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
Chris@12:      * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
Chris@12:      *
Chris@12:      * An example of such an opening is:
Chris@12:      *
Chris@12:      * ```
Chris@12:      * /**#@+
Chris@12:      *  * My DocBlock
Chris@12:      *  * /
Chris@12:      * ```
Chris@12:      *
Chris@12:      * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
Chris@12:      * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
Chris@12:      *
Chris@12:      * @see self::isTemplateEnd() for the check whether a closing marker was provided.
Chris@12:      *
Chris@12:      * @return boolean
Chris@12:      */
Chris@12:     public function isTemplateStart()
Chris@12:     {
Chris@12:         return $this->isTemplateStart;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns whether this DocBlock is the end of a Template section.
Chris@12:      *
Chris@12:      * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
Chris@12:      *
Chris@12:      * @return boolean
Chris@12:      */
Chris@12:     public function isTemplateEnd()
Chris@12:     {
Chris@12:         return $this->isTemplateEnd;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns the tags for this DocBlock.
Chris@12:      *
Chris@12:      * @return Tag[]
Chris@12:      */
Chris@12:     public function getTags()
Chris@12:     {
Chris@12:         return $this->tags;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Returns an array of tags matching the given name. If no tags are found
Chris@12:      * an empty array is returned.
Chris@12:      *
Chris@12:      * @param string $name String to search by.
Chris@12:      *
Chris@12:      * @return Tag[]
Chris@12:      */
Chris@12:     public function getTagsByName($name)
Chris@12:     {
Chris@12:         Assert::string($name);
Chris@12: 
Chris@12:         $result = [];
Chris@12: 
Chris@12:         /** @var Tag $tag */
Chris@12:         foreach ($this->getTags() as $tag) {
Chris@12:             if ($tag->getName() !== $name) {
Chris@12:                 continue;
Chris@12:             }
Chris@12: 
Chris@12:             $result[] = $tag;
Chris@12:         }
Chris@12: 
Chris@12:         return $result;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Checks if a tag of a certain type is present in this DocBlock.
Chris@12:      *
Chris@12:      * @param string $name Tag name to check for.
Chris@12:      *
Chris@12:      * @return bool
Chris@12:      */
Chris@12:     public function hasTag($name)
Chris@12:     {
Chris@12:         Assert::string($name);
Chris@12: 
Chris@12:         /** @var Tag $tag */
Chris@12:         foreach ($this->getTags() as $tag) {
Chris@12:             if ($tag->getName() === $name) {
Chris@12:                 return true;
Chris@12:             }
Chris@12:         }
Chris@12: 
Chris@12:         return false;
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Remove a tag from this DocBlock.
Chris@12:      *
Chris@12:      * @param Tag $tag The tag to remove.
Chris@12:      *
Chris@12:      * @return void
Chris@12:      */
Chris@12:     public function removeTag(Tag $tagToRemove)
Chris@12:     {
Chris@12:         foreach ($this->tags as $key => $tag) {
Chris@12:             if ($tag === $tagToRemove) {
Chris@12:                 unset($this->tags[$key]);
Chris@12:                 break;
Chris@12:             }
Chris@12:         }
Chris@12:     }
Chris@12: 
Chris@12:     /**
Chris@12:      * Adds a tag to this DocBlock.
Chris@12:      *
Chris@12:      * @param Tag $tag The tag to add.
Chris@12:      *
Chris@12:      * @return void
Chris@12:      */
Chris@12:     private function addTag(Tag $tag)
Chris@12:     {
Chris@12:         $this->tags[] = $tag;
Chris@12:     }
Chris@12: }