Factory method responsible for instantiating the correct sub type.
|
final public static createInstance ( string $tag_line, |
||
| $tag_line | string | The text for this tag, including description. |
| $docblock | The DocBlock which this tag belongs to. | |
| $location | phpDocumentor\Reflection\DocBlock\Location | Location of the tag. |
| Résultat | static | A new tag object. |
/**
* Generate docblock.
*
* @param string $class
* @param array $properties
* @param array $methods
* @return mixed
*/
public function docblock($class, $properties, $methods)
{
$phpdoc = new DocBlock('');
$phpdoc->setText($class);
foreach ($properties as $property) {
$tag = Tag::createInstance("@{$property['type']} {$property['return']} {$property['name']}", $phpdoc);
$phpdoc->appendTag($tag);
}
foreach ($methods as $method) {
$tag = Tag::createInstance("@method {$method['type']} {$method['return']} {$method['name']}({$method['arguments']})", $phpdoc);
$phpdoc->appendTag($tag);
}
$serializer = new DocBlockSerializer();
$docComment = $serializer->getDocComment($phpdoc);
return $docComment;
}
/**
* @param string $class
* @return string
*/
protected function createPhpDocs($class)
{
$reflection = new \ReflectionClass($class);
$namespace = $reflection->getNamespaceName();
$classname = $reflection->getShortName();
$originalDoc = $reflection->getDocComment();
if ($this->reset) {
$phpdoc = new DocBlock('', new Context($namespace));
} else {
$phpdoc = new DocBlock($reflection, new Context($namespace));
}
if (!$phpdoc->getText()) {
$phpdoc->setText($class);
}
$properties = array();
$methods = array();
foreach ($phpdoc->getTags() as $tag) {
$name = $tag->getName();
if ($name == "property" || $name == "property-read" || $name == "property-write") {
$properties[] = $tag->getVariableName();
} elseif ($name == "method") {
$methods[] = $tag->getMethodName();
}
}
foreach ($this->properties as $name => $property) {
$name = "\${$name}";
if (in_array($name, $properties)) {
continue;
}
if ($property['read'] && $property['write']) {
$attr = 'property';
} elseif ($property['write']) {
$attr = 'property-write';
} else {
$attr = 'property-read';
}
$tag = Tag::createInstance("@{$attr} {$property['type']} {$name} {$property['comment']}", $phpdoc);
$phpdoc->appendTag($tag);
}
foreach ($this->methods as $name => $method) {
if (in_array($name, $methods)) {
continue;
}
$arguments = implode(', ', $method['arguments']);
$tag = Tag::createInstance("@method static {$method['type']} {$name}({$arguments})", $phpdoc);
$phpdoc->appendTag($tag);
}
$serializer = new DocBlockSerializer();
$serializer->getDocComment($phpdoc);
$docComment = $serializer->getDocComment($phpdoc);
if ($this->write) {
$filename = $reflection->getFileName();
$contents = \File::get($filename);
if ($originalDoc) {
$contents = str_replace($originalDoc, $docComment, $contents);
} else {
$needle = "class {$classname}";
$replace = "{$docComment}\nclass {$classname}";
$pos = strpos($contents, $needle);
if ($pos !== false) {
$contents = substr_replace($contents, $replace, $pos, strlen($needle));
}
}
if (\File::put($filename, $contents)) {
$this->info('Written new phpDocBlock to ' . $filename);
}
}
$output = "namespace {$namespace}{\n{$docComment}\n\tclass {$classname} {}\n}\n\n";
return $output;
}
/**
* @param \ReflectionMethod $method
* @param string $alias
* @param string $class
* @param string|null $methodName
* @param array $interfaces
*/
public function __construct(\ReflectionMethod $method, $alias, $class, $methodName = null, $interfaces = array())
{
$this->method = $method;
$this->interfaces = $interfaces;
$this->name = $methodName ?: $method->name;
$this->namespace = $method->getDeclaringClass()->getNamespaceName();
//Create a DocBlock and serializer instance
$this->phpdoc = new DocBlock($method, new Context($this->namespace));
//Normalize the description and inherit the docs from parents/interfaces
try {
$this->normalizeParams($this->phpdoc);
$this->normalizeReturn($this->phpdoc);
$this->normalizeDescription($this->phpdoc);
} catch (\Exception $e) {
}
//Get the parameters, including formatted default values
$this->getParameters($method);
//Make the method static
$this->phpdoc->appendTag(Tag::createInstance('@static', $this->phpdoc));
//Reference the 'real' function in the declaringclass
$declaringClass = $method->getDeclaringClass();
$this->declaringClassName = '\\' . ltrim($declaringClass->name, '\\');
$this->root = '\\' . ltrim($class->getName(), '\\');
}
/**
* Creates the tag objects.
*
* @param string $tags Tag block to parse.
*
* @return void
*/
protected function parseTags($tags)
{
$result = array();
$tags = trim($tags);
if ('' !== $tags) {
if ('@' !== $tags[0]) {
throw new \LogicException('A tag block started with text instead of an actual tag,' . ' this makes the tag block invalid: ' . $tags);
}
foreach (explode("\n", $tags) as $tag_line) {
if (isset($tag_line[0]) && $tag_line[0] === '@') {
$result[] = $tag_line;
} else {
$result[count($result) - 1] .= "\n" . $tag_line;
}
}
// create proper Tag objects
foreach ($result as $key => $tag_line) {
$result[$key] = Tag::createInstance(trim($tag_line), $this);
}
}
$this->tags = $result;
}
/**
* Creates a Tag Reflector from the given array of tag line, tag name and tag content.
*
* @param string[] $match
*
* @return Tag
*/
private function createLinkOrSeeTagFromRegexMatch(array $match)
{
list($completeMatch, $tagName, $tagContent) = $match;
return Tag::createInstance('@' . $tagName . ' ' . $tagContent);
}
/**
* Returns 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 getParsedContents()
{
if (null === $this->parsedContents) {
$this->parsedContents = preg_split('/\\{
# "{@}" is not a valid inline tag. This ensures that
# we do not treat it as one, but treat it literally.
(?!@\\})
# We want to capture the whole tag line, but without the
# inline tag delimiters.
(\\@
# Match everything up to the next delimiter.
[^{}]*
# Nested inline tag content should not be captured, or
# it will appear in the result separately.
(?:
# Match nested inline tags.
(?:
# Because we did not catch the tag delimiters
# earlier, we must be explicit with them here.
# Notice that this also matches "{}", as a way
# to later introduce it as an escape sequence.
\\{(?1)?\\}
|
# Make sure we match hanging "{".
\\{
)
# Match content after the nested inline tag.
[^{}]*
)* # If there are more inline tags, match them as well.
# We use "*" since there may not be any nested inline
# tags.
)
\\}/Sux', $this->contents, null, PREG_SPLIT_DELIM_CAPTURE);
$count = count($this->parsedContents);
for ($i = 1; $i < $count; $i += 2) {
$this->parsedContents[$i] = Tag::createInstance($this->parsedContents[$i], $this->docblock);
}
//In order to allow "literal" inline tags, the otherwise invalid
//sequence "{@}" is changed to "@", and "{}" is changed to "}".
//See unit tests for examples.
for ($i = 0; $i < $count; $i += 2) {
$this->parsedContents[$i] = str_replace(array('{@}', '{}'), array('@', '}'), $this->parsedContents[$i]);
}
}
return $this->parsedContents;
}
/**
* @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
*
* @return void
*/
public function testIncompatibleTagHandlerRegistration()
{
$currentHandler = __NAMESPACE__ . '\\Tag\\VarTag';
$tagPreReg = Tag::createInstance('@var mixed');
$this->assertInstanceOf($currentHandler, $tagPreReg);
$this->assertInstanceOf(__NAMESPACE__ . '\\Tag', $tagPreReg);
$this->assertFalse(Tag::registerTagHandler('var', __NAMESPACE__ . '\\TagTest'));
$tagPostReg = Tag::createInstance('@var mixed');
$this->assertInstanceOf($currentHandler, $tagPostReg);
$this->assertInstanceOf(__NAMESPACE__ . '\\Tag', $tagPostReg);
}
/**
* Creates the tag objects.
*
* @param string $tags Tag block to parse.
*
* @return void
*/
protected function parseTags($tags)
{
$result = array();
$tags = trim($tags);
if ('' !== $tags) {
if ('@' !== $tags[0]) {
throw new \LogicException('A tag block started with text instead of an actual tag,' . ' this makes the tag block invalid: ' . $tags);
}
foreach (explode("\n", $tags) as $tag_line) {
if (isset($tag_line[0]) && $tag_line[0] === '@') {
$result[] = $tag_line;
} else {
$result[count($result) - 1] .= "\n" . $tag_line;
}
}
// create proper Tag objects
foreach ($result as $key => $tag_line) {
$tag = Tag::createInstance(trim($tag_line), $this);
$result[$key] = ['tag' => $tag->getName(), 'type' => explode(' ', $tag->getContent())[0], 'param' => str_replace('$', '', @explode(' ', $tag->getContent())[1])];
}
}
$this->tags = $result;
}
/**
* @param \ReflectionMethod $method
* @param string $alias
* @param $class
* @param null $methodName
* @return string
*/
protected function parseMethod($method, $alias, $class, $methodName = null)
{
$output = '';
// Don't add the __clone() functions
if ($method->name === '__clone') {
return $output;
}
$methodName = $methodName ?: $method->name;
$namespace = $method->getDeclaringClass()->getNamespaceName();
//Create a DocBlock and serializer instance
$phpdoc = new DocBlock($method, new Context($namespace));
$serializer = new DocBlockSerializer(1, "\t\t");
//Normalize the description and inherit the docs from parents/interfaces
try {
$this->normalizeDescription($phpdoc, $method);
} catch (\Exception $e) {
$this->info("Cannot normalize method {$alias}::{$methodName}..");
}
//Correct the return values
$returnValue = $this->getReturn($phpdoc);
//Get the parameters, including formatted default values
list($params, $paramsWithDefault) = $this->getParameters($method);
//Make the method static
$phpdoc->appendTag(Tag::createInstance('@static', $phpdoc));
//Write the output, using the DocBlock serializer
$output .= $serializer->getDocComment($phpdoc) . "\n\t\t public static function " . $methodName . "(";
$output .= implode($paramsWithDefault, ", ");
$output .= "){\n";
//Only return when not a constructor and not void.
$return = $returnValue && $returnValue !== "void" && $method->name !== "__construct" ? 'return' : '';
//Reference the 'real' function in the declaringclass
$declaringClass = $method->getDeclaringClass();
$declaringClassName = '\\' . ltrim($declaringClass->name, '\\');
$root = '\\' . ltrim($class->getName(), '\\');
if ($declaringClass->name != $root) {
$output .= "\t\t\t//Method inherited from {$declaringClassName}\n";
}
$output .= "\t\t\t{$return} {$root}::";
//Write the default parameters in the function call
$output .= $method->name . "(" . implode($params, ", ") . ");\n";
$output .= "\t\t }\n\n";
return $output;
}
