/**
* 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;
}
/**
* Parses doc comment and populates comment entity
*
* @param string $text
*/
protected function parseDoc(Comment $comment, $text)
{
$context = $this->getContext();
try {
$block = new DocBlock($text, $context);
foreach ($block->getTags() as $tag) {
switch ($tag->getName()) {
case "param":
$comment->addVar($this->createMethodParam($tag));
break;
case "var":
$comment->addVar($this->createVar($tag));
break;
case "return":
$comment->setReturn($this->getFQCN($tag->getType()));
break;
case "property":
$comment->addProperty($this->createProperty($tag));
break;
case "inheritdoc":
$comment->markInheritDoc();
break;
}
}
} catch (\Exception $e) {
}
}
/**
* Constructor
*
* @param string $name Name of the "entity"
* @param DocBlock|null $docblock Docblock
* @param BaseReflector|null $source Source Element.
*/
public function __construct($name, $docblock = null, $source = null)
{
$this->entityName = $name;
$this->lineNumber = $docblock ? $docblock->getLocation()->getLineNumber() : $source->getLineNumber();
$this->docblock = $docblock;
$this->source = $source;
}
protected function configure()
{
$reflection = new \ReflectionClass(get_called_class());
$baseNamespaceChunks = [];
foreach (explode('\\', $reflection->getNamespaceName()) as $namespaceChunk) {
$baseNamespaceChunks[] = $namespaceChunk;
if ($namespaceChunk == consoleBase::COMMANDS_DIRECTORY) {
break;
}
}
$namespace = str_replace(implode('\\', $baseNamespaceChunks), '', get_called_class());
$namespace = trim($namespace, '\\');
$commandNameData = explode('\\', $namespace);
$phpdoc = new DocBlock($reflection);
/** @var DocBlock\Tag $tag */
$tag = reset($phpdoc->getTagsByName('consoleNs'));
$commandNameValues = [];
if ($tag) {
$consoleNs = trim($tag->getDescription());
if (!empty($consoleNs)) {
$commandNameValues[] = $consoleNs;
}
}
foreach ($commandNameData as $commandNameValue) {
$commandNameValues[] = $commandNameValue;
}
$this->setName(implode(':', $commandNameValues))->setDescription($phpdoc->getShortDescription())->setHelp($phpdoc->getLongDescription());
$this->defineArguments();
}
protected function getProperties($propertyName)
{
$reflection = new \ReflectionClass($this->model);
$docBlock = new DocBlock($reflection);
$properties = $docBlock->getTagsByName($propertyName);
return $this->buildProperties($properties);
}
/**
* Constructor
*
* @param \phpDocumentor\Plugin\Plugin $plugin Plugin to which this
* validator belongs.
* @param string $name Name of the "entity"
* @param \phpDocumentor\Reflection\DocBlock|null $docblock Docblock
* @param \phpDocumentor\Reflection\BaseReflector|null $source Source Element.
*/
public function __construct($plugin, $name, $docblock = null, $source = null)
{
$this->entityName = $name;
$this->lineNumber = $docblock ? $docblock->getLocation()->getLineNumber() : $source->getLineNumber();
$this->docblock = $docblock;
$this->source = $source;
parent::__construct($plugin->getEventDispatcher(), $plugin->getConfiguration(), $plugin->getTranslator());
}
/**
* Parse the docBlock comment for this command, and set the
* fields of this class with the data thereby obtained.
*/
public function parse()
{
$docblockComment = $this->reflection->getDocComment();
$phpdoc = new DocBlock($docblockComment);
// First set the description (synopsis) and help.
$this->commandInfo->setDescription((string) $phpdoc->getShortDescription());
$this->commandInfo->setHelp((string) $phpdoc->getLongDescription());
$this->processAllTags($phpdoc);
}
/**
* @param string $method
* @return array
*/
public function getMethodDecorators($method)
{
$reflectionMethod = new \ReflectionMethod($this->getInstance(), $method);
$docBlock = new DocBlock($reflectionMethod);
$decorators = [];
foreach ($docBlock->getTagsByName(static::TAG_NAME) as $tag) {
$decorators[] = $tag->getContent();
}
return $decorators;
}
/**
* Extracts the package from the DocBlock.
*
* @param DocBlock $docBlock
*
* @return string|null
*/
protected function extractPackageFromDocBlock($docBlock)
{
$packageTags = $docBlock ? $docBlock->getTagsByName('package') : null;
if (!$packageTags) {
return null;
}
/** @var DocBlock\Tag $tag */
$tag = reset($packageTags);
return trim($tag->getContent());
}
/**
* @param \ReflectionProperty $reflectionProperty
*
* @return string|null
*/
public function detectType(\ReflectionProperty $reflectionProperty)
{
$docBlock = new DocBlock($reflectionProperty->getDocComment());
$tags = $docBlock->getTagsByName('var');
if (count($tags) == 0) {
return null;
}
/** @var VarTag $typeTag */
$typeTag = reset($tags);
return $typeTag->getType();
}
/**
* Discover Magical API
*
* @param ClassNode $node
*/
public function apply(ClassNode $node)
{
$parentClass = $node->getParentClass();
$reflectionClass = new \ReflectionClass($parentClass);
$phpdoc = new DocBlock($reflectionClass->getDocComment());
$tagList = $phpdoc->getTagsByName('method');
foreach ($tagList as $tag) {
$methodNode = new MethodNode($tag->getMethodName());
$methodNode->setStatic($tag->isStatic());
$node->addMethod($methodNode);
}
}
/**
*
* @param ReflectionProperty $reflector
* @return ParsePropertyBlockResult
*/
public function parsePropertyDocBlock(ReflectionProperty $reflector)
{
$phpdoc = new DocBlock($reflector->getDocComment());
/* @var $varTags VarTag[] */
$varTags = $phpdoc->getTagsByName("var");
/* @var $varTag VarTag */
$varTag = $varTags[0];
$result = new ParsePropertyBlockResult();
$result->description = $phpdoc->getShortDescription();
$result->type = (string) $varTag->getType();
return $result;
}
/**
* @param $doc
* @return bool
*/
public function parseClass(ControllerDoc $doc)
{
if (!($docBlock = new DocBlock($this->reflection))) {
return false;
}
$doc->longDescription = $docBlock->getLongDescription()->getContents();
$doc->shortDescription = $docBlock->getShortDescription();
$doc->populateTags($docBlock);
if (DocBlockHelper::isInherit($docBlock)) {
$parentParser = $this->getParentParser();
$parentParser->parseClass($doc);
}
}
/**
* Given a property, attempt to find the type of the property.
*
* @param ReflectionProperty $reflectionProperty
* @return Type[]
*/
public function __invoke(ReflectionProperty $reflectionProperty)
{
$contextFactory = new ContextFactory();
$context = $contextFactory->createForNamespace($reflectionProperty->getDeclaringClass()->getNamespaceName(), $reflectionProperty->getDeclaringClass()->getLocatedSource()->getSource());
$docBlock = new DocBlock($reflectionProperty->getDocComment(), new DocBlock\Context($context->getNamespace(), $context->getNamespaceAliases()));
/* @var \phpDocumentor\Reflection\DocBlock\Tag\VarTag $varTag */
$resolvedTypes = [];
$varTags = $docBlock->getTagsByName('var');
foreach ($varTags as $varTag) {
$resolvedTypes = array_merge($resolvedTypes, (new ResolveTypes())->__invoke($varTag->getTypes(), $context));
}
return $resolvedTypes;
}
/**
* Given a function and parameter, attempt to find the type of the parameter.
*
* @param ReflectionFunctionAbstract $function
* @param ParamNode $node
* @return Type[]
*/
public function __invoke(ReflectionFunctionAbstract $function, ParamNode $node)
{
$context = $this->createContextForFunction($function);
$docBlock = new DocBlock($function->getDocComment(), new DocBlock\Context($context->getNamespace(), $context->getNamespaceAliases()));
$paramTags = $docBlock->getTagsByName('param');
foreach ($paramTags as $paramTag) {
/* @var $paramTag \phpDocumentor\Reflection\DocBlock\Tag\ParamTag */
if ($paramTag->getVariableName() === '$' . $node->name) {
return (new ResolveTypes())->__invoke($paramTag->getTypes(), $context);
}
}
return [];
}
/**
* {@inheritDoc}
*/
public function extractAction(ActionInterface $action)
{
$callable = $this->callableResolver->resolve($action);
if ($this->parameterExtractor) {
$parameters = $this->parameterExtractor->extract($action, $callable);
} else {
$parameters = [];
}
$reflection = $callable->getReflection();
$docBlock = new DocBlock($reflection);
$description = $docBlock->getShortDescription();
$actionDoc = new Action($action->getName(), $description, $parameters);
return $actionDoc;
}
/**
* 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)
{
$matches = self::extractTagParts($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);
}
/**
* Process comments into docblock objects.
* @param array $docblocks
*/
protected function processDocBlocks(array $docblocks)
{
$this->docblocks = array();
foreach ($docblocks as $raw_docblock) {
$docblock = new DocBlock($raw_docblock);
$tags = $docblock->getTagsByName("var");
foreach ($tags as $tag) {
if ($tag && ($description = $tag->getDescription())) {
list($key, ) = explode(' ', $description);
$this->docblocks[$key] = $docblock;
}
}
}
}
/**
* Extracts tags from docBlock and adds it to document.
*
* @param DocBlock $docBlock
*/
public function populateTags(DocBlock $docBlock)
{
$tags = $docBlock->getTags();
$offset = strlen(self::TAG_PREFIX);
foreach ($tags as $tag) {
$name = $tag->getName();
if (strpos($name, self::TAG_PREFIX) === 0) {
$key = substr($name, $offset);
if (!isset($this->_tags)) {
$this->_tags[$key] = [];
}
$this->_tags[$key][] = $tag;
}
}
}
protected function setParentsPackage(\DOMElement $parent, \phpDocumentor\Reflection\DocBlock $docblock, $element)
{
/** @var \phpDocumentor\Reflection\DocBlock\Tag $package */
$package = current($docblock->getTagsByName('package'));
/** @var \phpDocumentor\Reflection\DocBlock\Tag $subpackage */
$subpackage = current($docblock->getTagsByName('subpackage'));
$package_name = '';
if ($package) {
$package_name = str_replace(array('.', '_'), '\\', $package->getContent() . ($subpackage ? '\\' . $subpackage->getContent() : ''));
}
if (!$package_name) {
$package_name = $element->getDefaultPackageName();
}
$parent->setAttribute('package', $package_name);
}
public function enterNode(Node $node)
{
parent::enterNode($node);
try {
if ($doc = $node->getDocComment()) {
$docBlock = new DocBlock($doc->getText());
if ($tagNames = $this->collectTagNamesBy($docBlock->getTags())) {
$node->setAttribute(self::TAG_NAMES_ATTRIBUTE, $tagNames);
}
}
} catch (\Exception $e) {
$parseError = new Error($e->getMessage(), $node->getLine());
$this->logger->warning($parseError->getMessage(), array($this->file));
}
}
/**
* 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('/^@([\\w\\-\\_\\\\]+)(?:\\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);
}
public function resolveSignature($comment)
{
$docblock = new DocBlock((string) $comment);
$return = $docblock->getTagsByName("return");
if (count($return) !== 1) {
$returnType = new Type(Type::TYPE_UNKNOWN);
} else {
$returnType = Type::normalizeType($return[0]->getType());
}
$params = $docblock->getTagsByName("param");
$paramTypes = [];
foreach ($params as $key => $param) {
$paramTypes[] = Type::normalizeType($params[$key]->getType());
}
return new Signature($returnType, $paramTypes);
}
/**
* {@inheritdoc}
*
* @param Type $class
* @param string $name
* @return Type
*/
public function getType(Type $class, $name)
{
$reflectionObject = new ReflectionClass($class->toString());
if (!$reflectionObject->hasProperty($name)) {
return Type::fromString(null);
}
$reflectionProperty = $reflectionObject->getProperty($name);
$contextFactory = new ContextFactory();
$context = $contextFactory->createFromReflector($reflectionProperty);
$phpdoc = new DocBlock($reflectionProperty, $this->convertToDocBlockContext($context));
/** @var VarTag[] $vars */
$vars = $phpdoc->getTagsByName('var');
if (count($vars) === 0) {
return Type::fromString(null);
}
return Type::fromString($vars[0]->getType());
}
/**
* @param \Reflector $reflector
* @param string $tagName
*
* @return string|null
*/
public function resolveElementType(\Reflector $reflector, $tagName)
{
$docBlock = new DocBlock($reflector);
$returnTags = $docBlock->getTagsByName($tagName);
/** @var ReturnTag $returnTag */
$returnTag = reset($returnTags);
$type = $returnTag->getType();
$isCollection = false;
if ($extractedType = $this->extractTypeFromCollectionType($type)) {
$isCollection = true;
$type = $extractedType;
}
if (static::isTypeObject($type) && ($reflector instanceof \ReflectionMethod || $reflector instanceof \ReflectionProperty)) {
$type = $this->resolveClassName($type, $reflector->getDeclaringClass());
}
return $type . ($isCollection ? '[]' : '');
}
public static function servicesListProvider()
{
$sp = _elgg_services();
$class = new \ReflectionClass(get_class($sp));
$phpdoc = new DocBlock($class);
$readonly_props = $phpdoc->getTagsByName('property-read');
/* @var \phpDocumentor\Reflection\DocBlock\Tag\PropertyReadTag[] $readonly_props */
foreach ($readonly_props as $prop) {
$name = substr($prop->getVariableName(), 1);
$type = $prop->getType();
// stuff set in PHPUnit bootstrap
if ($name === 'mailer') {
$type = InMemory::class;
}
$sets[] = [$name, $type];
}
return $sets;
}
/**
* Given a property, attempt to find the type of the property
*
* @param PropertyNode $node
* @param ReflectionProperty $reflectionProperty
* @return Type[]
*/
public function __invoke(PropertyNode $node, ReflectionProperty $reflectionProperty)
{
$contextFactory = new ContextFactory();
$context = $contextFactory->createForNamespace($reflectionProperty->getDeclaringClass()->getNamespaceName(), $reflectionProperty->getDeclaringClass()->getLocatedSource()->getSource());
/* @var \PhpParser\Comment\Doc $comment */
if (!$node->hasAttribute('comments')) {
return [];
}
$comment = $node->getAttribute('comments')[0];
$docBlock = new DocBlock($comment->getReformattedText(), new DocBlock\Context($context->getNamespace(), $context->getNamespaceAliases()));
/* @var \phpDocumentor\Reflection\DocBlock\Tag\VarTag $varTag */
$resolvedTypes = [];
$varTags = $docBlock->getTagsByName('var');
foreach ($varTags as $varTag) {
$resolvedTypes = array_merge($resolvedTypes, (new ResolveTypes())->__invoke($varTag->getTypes(), $context));
}
return $resolvedTypes;
}
/**
* Discover Magical API
*
* @param ClassNode $node
*/
public function apply(ClassNode $node)
{
$parentClass = $node->getParentClass();
$reflectionClass = new \ReflectionClass($parentClass);
$phpdoc = new DocBlock($reflectionClass->getDocComment());
$tagList = $phpdoc->getTagsByName('method');
$interfaces = $reflectionClass->getInterfaces();
foreach ($interfaces as $interface) {
$phpdoc = new DocBlock($interface);
$tagList = array_merge($tagList, $phpdoc->getTagsByName('method'));
}
foreach ($tagList as $tag) {
$methodName = $tag->getMethodName();
if (!$reflectionClass->hasMethod($methodName)) {
$methodNode = new MethodNode($tag->getMethodName());
$methodNode->setStatic($tag->isStatic());
$node->addMethod($methodNode);
}
}
}
/**
* Returns an array of endpoints
*
* @return array
*/
protected function getEndpoints()
{
$endpoints = [];
foreach ($this->routes as $route) {
$array = explode("@", $route['action']);
$class = $array[0];
if ($class == "Closure") {
// check for api/v1/docs
if (strpos($route['uri'], $this->prefix . '/docs') !== false) {
continue;
}
}
$reflector = new ReflectionClass($class);
$docBlock = new DocBlock($reflector);
// remove Controller
$class = str_replace('Controller', '', $class);
$endpoints["{$class}"]['methods'] = [];
$endpoints["{$class}"]['description'] = $docBlock->getShortDescription();
}
return $this->getEndpointMethods($endpoints);
}
public function fetchMethod($className, $method)
{
$phpdoc = new DocBlock($method->getDocComment());
$call = array();
$params = array();
$return = null;
// build the call example string
foreach ($method->getParameters() as $param) {
if ($param->isOptional()) {
try {
$value = var_export($param->getDefaultValue(), true);
$value = str_replace(PHP_EOL, '', $value);
$value = str_replace('NULL', 'null', $value);
$value = str_replace('array ()', 'array()', $value);
$call[] = '$' . $param->getName() . ' = ' . $value;
} catch (Exception $e) {
$call[] = '$' . $param->getName();
}
} else {
$call[] = '$' . $param->getName();
}
}
// get all parameter docs
foreach ($phpdoc->getTags() as $tag) {
switch ($tag->getName()) {
case 'param':
$params[] = array('name' => $tag->getVariableName(), 'type' => $tag->getType(), 'text' => $tag->getDescription());
break;
case 'return':
$return = array('type' => $tag->getType(), 'text' => $tag->getDescription());
break;
}
}
// a::first
$methodName = strtolower($className) . '::' . $method->getName();
$methodSlug = str::slug($method->getName());
// build the full method array
return array('name' => $methodName, 'slug' => $methodSlug, 'excerpt' => str_replace(PHP_EOL, ' ', $phpdoc->getShortDescription()), 'call' => $methodName . '(' . implode(', ', $call) . ')', 'return' => $return, 'params' => $params);
}
