class Description

Object representing to description for a DocBlock.

A Description object can consist of plain text but can also include tags. A Description Formatter can then combine a body template with sprintf-style placeholders together with formatted tags in order to reconstitute a complete description text using the format that you would prefer.

Because parsing a Description text can be a verbose process this is handled by the {thus recommended to use that to create a Description object, like this:

$description = $descriptionFactory->create('This is a { The description factory will interpret the given body and create a body template and list of tags from them, and pass that onto the constructor if this class.

> The $context variable is a class of type {> and the namespace aliases that apply to this DocBlock. These are used by the Factory to resolve and expand partial > type names and FQSENs.

If you do not want to use the DescriptionFactory you can pass a body template and tag listing like this:

$description = new Description( 'This is a %1$s', [ new See(new Fqsen('\phpDocumentor\Reflection\DocBlock\Description')) ] );

It is generally recommended to use the Factory as that will also apply escaping rules, while the Description object is mainly responsible for rendering.

Hierarchy

• class \phpDocumentor\Reflection\DocBlock\Description

Expanded class hierarchy of Description

See also

DescriptionFactory}. It is

Description}', $context);

\phpDocumentor\Reflection\Types\Context} and contains the namespace

DescriptionFactory to create a new Description.

Tags\Formatter for the formatting of the body and tags.

File

vendor/phpdocumentor/reflection-docblock/src/DocBlock/Description.php, line 53

Namespace

class Description {
    private string $bodyTemplate;
    
    /** @var Tag[] */
    private array $tags;
    
    /**
     * Initializes a Description with its body (template) and a listing of the tags used in the body template.
     *
     * @param Tag[] $tags
     */
    public function __construct(string $bodyTemplate, array $tags = []) {
        $this->bodyTemplate = $bodyTemplate;
        $this->tags = $tags;
    }
    
    /**
     * Returns the body template.
     */
    public function getBodyTemplate() : string {
        return $this->bodyTemplate;
    }
    
    /**
     * Returns the tags for this DocBlock.
     *
     * @return Tag[]
     */
    public function getTags() : array {
        return $this->tags;
    }
    
    /**
     * Renders this description as a string where the provided formatter will format the tags in the expected string
     * format.
     */
    public function render(?Formatter $formatter = null) : string {
        if ($this->tags === []) {
            return vsprintf($this->bodyTemplate, []);
        }
        if ($formatter === null) {
            $formatter = new PassthroughFormatter();
        }
        $tags = [];
        foreach ($this->tags as $tag) {
            $tags[] = '{' . $formatter->format($tag) . '}';
        }
        return vsprintf($this->bodyTemplate, $tags);
    }
    
    /**
     * Returns a plain string representation of this description.
     */
    public function __toString() : string {
        return $this->render();
    }

}

Members