Tag.php in Zircon Profile 8

Namespace

phpDocumentor\Reflection\DocBlock

File

vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock/Tag.php

<?php

/**
 * phpDocumentor
 *
 * PHP Version 5.3
 *
 * @author    Mike van Riel <[e-mail]>
 * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
 * @link      http://phpdoc.org
 */
namespace phpDocumentor\Reflection\DocBlock;

use phpDocumentor\Reflection\DocBlock;

/**
 * Parses a tag definition for a DocBlock.
 *
 * @author  Mike van Riel <[e-mail]>
 * @license http://www.opensource.org/licenses/mit-license.php MIT
 * @link    http://phpdoc.org
 */
class Tag implements \Reflector {

  /**
   * PCRE regular expression matching a tag name.
   */
  const REGEX_TAGNAME = '[\\w\\-\\_\\\\]+';

  /** @var string Name of the tag */
  protected $tag = '';

  /**
   * @var string|null Content of the tag.
   *     When set to NULL, it means it needs to be regenerated.
   */
  protected $content = '';

  /** @var string Description of the content of this tag */
  protected $description = '';

  /**
   * @var array|null The description, as an array of strings and Tag objects.
   *     When set to NULL, it means it needs to be regenerated.
   */
  protected $parsedDescription = null;

  /** @var Location Location of the tag. */
  protected $location = null;

  /** @var DocBlock The DocBlock which this tag belongs to. */
  protected $docblock = null;

  /**
   * @var array An array with a tag as a key, and an FQCN to a class that
   *     handles it as an array value. The class is expected to inherit this
   *     class.
   */
  private static $tagHandlerMappings = array(
    'author' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\AuthorTag',
    'covers' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\CoversTag',
    'deprecated' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\DeprecatedTag',
    'example' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\ExampleTag',
    'link' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\LinkTag',
    'method' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\MethodTag',
    'param' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\ParamTag',
    'property-read' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\PropertyReadTag',
    'property' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\PropertyTag',
    'property-write' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\PropertyWriteTag',
    'return' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\ReturnTag',
    'see' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\SeeTag',
    'since' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\SinceTag',
    'source' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\SourceTag',
    'throw' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\ThrowsTag',
    'throws' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\ThrowsTag',
    'uses' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\UsesTag',
    'var' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\VarTag',
    'version' => '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\VersionTag',
  );

  /**
   * Factory method responsible for instantiating the correct sub type.
   *
   * @param string   $tag_line The text for this tag, including description.
   * @param DocBlock $docblock The DocBlock which this tag belongs to.
   * @param Location $location Location of the tag.
   *
   * @throws \InvalidArgumentException if an invalid tag line was presented.
   *
   * @return static A new tag object.
   */
  public static final function createInstance($tag_line, DocBlock $docblock = null, Location $location = null) {
    if (!preg_match('/^@(' . self::REGEX_TAGNAME . ')(?:\\s*([^\\s].*)|$)?/us', $tag_line, $matches)) {
      throw new \InvalidArgumentException('Invalid tag_line detected: ' . $tag_line);
    }
    $handler = __CLASS__;
    if (isset(self::$tagHandlerMappings[$matches[1]])) {
      $handler = self::$tagHandlerMappings[$matches[1]];
    }
    elseif (isset($docblock)) {
      $tagName = (string) new Type\Collection(array(
        $matches[1],
      ), $docblock
        ->getContext());
      if (isset(self::$tagHandlerMappings[$tagName])) {
        $handler = self::$tagHandlerMappings[$tagName];
      }
    }
    return new $handler($matches[1], isset($matches[2]) ? $matches[2] : '', $docblock, $location);
  }

  /**
   * Registers a handler for tags.
   *
   * Registers a handler for tags. The class specified is autoloaded if it's
   * not available. It must inherit from this class.
   *
   * @param string      $tag     Name of tag to regiser a handler for. When
   *     registering a namespaced tag, the full name, along with a prefixing
   *     slash MUST be provided.
   * @param string|null $handler FQCN of handler. Specifing NULL removes the
   *     handler for the specified tag, if any.
   *
   * @return bool TRUE on success, FALSE on failure.
   */
  public static final function registerTagHandler($tag, $handler) {
    $tag = trim((string) $tag);
    if (null === $handler) {
      unset(self::$tagHandlerMappings[$tag]);
      return true;
    }
    if ('' !== $tag && class_exists($handler, true) && is_subclass_of($handler, __CLASS__) && !strpos($tag, '\\')) {
      self::$tagHandlerMappings[$tag] = $handler;
      return true;
    }
    return false;
  }

  /**
   * Parses a tag and populates the member variables.
   *
   * @param string   $name     Name of the tag.
   * @param string   $content  The contents of the given tag.
   * @param DocBlock $docblock The DocBlock which this tag belongs to.
   * @param Location $location Location of the tag.
   */
  public function __construct($name, $content, DocBlock $docblock = null, Location $location = null) {
    $this
      ->setName($name)
      ->setContent($content)
      ->setDocBlock($docblock)
      ->setLocation($location);
  }

  /**
   * Gets the name of this tag.
   *
   * @return string The name of this tag.
   */
  public function getName() {
    return $this->tag;
  }

  /**
   * Sets the name of this tag.
   *
   * @param string $name The new name of this tag.
   *
   * @return $this
   * @throws \InvalidArgumentException When an invalid tag name is provided.
   */
  public function setName($name) {
    if (!preg_match('/^' . self::REGEX_TAGNAME . '$/u', $name)) {
      throw new \InvalidArgumentException('Invalid tag name supplied: ' . $name);
    }
    $this->tag = $name;
    return $this;
  }

  /**
   * Gets the content of this tag.
   *
   * @return string
   */
  public function getContent() {
    if (null === $this->content) {
      $this->content = $this->description;
    }
    return $this->content;
  }

  /**
   * Sets the content of this tag.
   *
   * @param string $content The new content of this tag.
   *
   * @return $this
   */
  public function setContent($content) {
    $this
      ->setDescription($content);
    $this->content = $content;
    return $this;
  }

  /**
   * Gets the description component of this tag.
   *
   * @return string
   */
  public function getDescription() {
    return $this->description;
  }

  /**
   * Sets the description component of this tag.
   *
   * @param string $description The new description component of this tag.
   *
   * @return $this
   */
  public function setDescription($description) {
    $this->content = null;
    $this->parsedDescription = null;
    $this->description = trim($description);
    return $this;
  }

  /**
   * Gets the parsed text of this description.
   *
   * @return array An array of strings and tag objects, in the order they
   *     occur within the description.
   */
  public function getParsedDescription() {
    if (null === $this->parsedDescription) {
      $description = new Description($this->description, $this->docblock);
      $this->parsedDescription = $description
        ->getParsedContents();
    }
    return $this->parsedDescription;
  }

  /**
   * Gets the docblock this tag belongs to.
   *
   * @return DocBlock The docblock this tag belongs to.
   */
  public function getDocBlock() {
    return $this->docblock;
  }

  /**
   * Sets the docblock this tag belongs to.
   *
   * @param DocBlock $docblock The new docblock this tag belongs to. Setting
   *     NULL removes any association.
   *
   * @return $this
   */
  public function setDocBlock(DocBlock $docblock = null) {
    $this->docblock = $docblock;
    return $this;
  }

  /**
   * Gets the location of the tag.
   *
   * @return Location The tag's location.
   */
  public function getLocation() {
    return $this->location;
  }

  /**
   * Sets the location of the tag.
   *
   * @param Location $location The new location of the tag.
   *
   * @return $this
   */
  public function setLocation(Location $location = null) {
    $this->location = $location;
    return $this;
  }

  /**
   * Builds a string representation of this object.
   *
   * @todo determine the exact format as used by PHP Reflection and implement it.
   *
   * @return void
   * @codeCoverageIgnore Not yet implemented
   */
  public static function export() {
    throw new \Exception('Not yet implemented');
  }

  /**
   * Returns the tag as a serialized string
   *
   * @return string
   */
  public function __toString() {
    return "@{$this->getName()} {$this->getContent()}";
  }

}

Classes

Name	Description
Tag	Parses a tag definition for a DocBlock.