/**
* 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;
}
/**
* Get the docblock for this method
*
* @param string $prefix
* @return mixed
*/
public function getDocComment($prefix = "\t\t")
{
$serializer = new DocBlockSerializer(1, $prefix);
return $serializer->getDocComment($this->phpdoc);
}
*
* This method is used to reconstitute a DocBlock into its original form by the {@see Serializer}. It should
* feature all parts of the tag so that the serializer can put it back together.
*
* @return string
*/
public function __toString()
{
return (string) $this->description;
}
}
$docComment = <<<DOCCOMMENT
/**
* This is an example of a summary.
*
* @my-tag I have a description
*/
DOCCOMMENT;
// Make a mapping between the tag name `my-tag` and the Tag class containing the Factory Method `create`.
$customTags = ['my-tag' => MyTag::class];
// Do pass the list of custom tags to the Factory for the DocBlockFactory.
$factory = DocBlockFactory::createInstance($customTags);
// You can also add Tags later using `$factory->registerTagHandler()` with a tag name and Tag class name.
// Create the DocBlock
$docblock = $factory->create($docComment);
// Take a look: the $customTagObjects now contain an array with your newly added tag
$customTagObjects = $docblock->getTagsByName('my-tag');
// As an experiment: let's reconstitute the DocBlock and observe that because we added a __toString() method
// to the tag class that we can now also see it.
$serializer = new Serializer();
$reconstitutedDocComment = $serializer->getDocComment($docblock);
/**
* Generation du docblock
*
* @param Docblock $docblock
* @return string
*/
public function docblock($docblock)
{
// On verifie que le trait est bien présent
$traits = class_uses($docblock);
if (!array_search(Docblock::class, $traits)) {
exc('la classe "' . get_class($docblock) . '" n\'utilise pas le trait "' . Docblock::class . '"');
}
$content = '/**' . PHP_EOL;
$content .= '* ' . $docblock->getSummary() . PHP_EOL;
$content .= '* ' . PHP_EOL;
$content .= '* ' . str_replace(PHP_EOL, PHP_EOL . '* ', $docblock->getDescription()) . PHP_EOL;
$content .= '* ' . PHP_EOL;
foreach ($docblock->getTags() as $tag) {
list($name, $value) = $tag;
$content .= sprintf('* @%s %s', $name, $value) . PHP_EOL;
}
$content .= '*/';
// on fait proprement mais bon!
// @todo passer sur la version 3 de phpdocumentor
$factory = new \phpDocumentor\Reflection\DocBlock($content);
$serializer = new Serializer();
$content = $serializer->getDocComment($factory) . PHP_EOL;
return $content;
}
/**
* @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;
}
/**
* @covers ::__construct
* @covers ::getDocComment
* @uses phpDocumentor\Reflection\DocBlock\Description
* @uses phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
* @uses phpDocumentor\Reflection\DocBlock
* @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
* @uses phpDocumentor\Reflection\DocBlock\Tags\Generic
*/
public function testWordwrapsAroundTheGivenAmountOfCharacters()
{
$expected = <<<'DOCCOMMENT'
/**
* This is a
* summary
*
* This is a
* description
*
* @unknown-tag
* Test
* description
* for the
* unknown tag
*/
DOCCOMMENT;
$fixture = new Serializer(0, '', true, 15);
$docBlock = new DocBlock('This is a summary', new Description('This is a description'), [new DocBlock\Tags\Generic('unknown-tag', new Description('Test description for the unknown tag'))]);
$this->assertSame($expected, $fixture->getDocComment($docBlock));
}
/**
* @param string $existingDocBlock
* @return string
*/
protected function mergeGeneratedTagsIntoDocBlock($existingDocBlock)
{
$docBlock = new DocBlock($this->removeExistingSupportedTags($existingDocBlock));
if (!$docBlock->getText()) {
$docBlock->setText('Class ' . $this->className);
}
foreach ($this->getGeneratedTags() as $tag) {
$docBlock->appendTag($tag);
}
$serializer = new DocBlockSerializer();
$docBlock = $serializer->getDocComment($docBlock);
return $docBlock;
}
