/**
* Returns description for method
* @return string
*/
public function description()
{
if (method_exists($this->action, 'description')) {
return $this->action->description();
}
return $this->docBlock ? $this->docBlock->getShortDescription() : '';
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @var string');
$reflectionTag = $docreflection->getTag('var');
/** @var GenericTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\GenericTag', $tag);
$this->assertEquals('var', $tag->getName());
$this->assertEquals('string', $tag->getContent());
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @throws Exception\\Invalid description');
$reflectionTag = $docreflection->getTag('throws');
/** @var ThrowsTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\ThrowsTag', $tag);
$this->assertEquals('description', $tag->getDescription());
$this->assertEquals('Exception\\Invalid', $tag->getTypesAsString());
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @author Mister Miller <*****@*****.**>');
$reflectionTag = $docreflection->getTag('author');
/** @var AuthorTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\AuthorTag', $tag);
$this->assertEquals('Mister Miller', $tag->getAuthorName());
$this->assertEquals('*****@*****.**', $tag->getAuthorEmail());
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @license http://zend.com License');
$reflectionTag = $docreflection->getTag('license');
/** @var LicenseTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\LicenseTag', $tag);
$this->assertEquals('http://zend.com', $tag->getUrl());
$this->assertEquals('License', $tag->getLicenseName());
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @return int The return');
$reflectionTag = $docreflection->getTag('return');
/** @var ReturnTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\ReturnTag', $tag);
$this->assertEquals('The return', $tag->getDescription());
$this->assertEquals('int', $tag->getTypesAsString());
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @property int $foo description');
$reflectionTag = $docreflection->getTag('property');
/** @var PropertyTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\PropertyTag', $tag);
$this->assertEquals('foo', $tag->getPropertyName());
$this->assertEquals('description', $tag->getDescription());
$this->assertEquals('int', $tag->getTypesAsString());
}
/**
* Build a DocBlock generator object from a reflection object
*
* @param DocBlockReflection $reflectionDocBlock
* @return DocBlockGenerator
*/
public static function fromReflection(DocBlockReflection $reflectionDocBlock)
{
$docBlock = new static();
$docBlock->setSourceContent($reflectionDocBlock->getContents());
$docBlock->setSourceDirty(false);
$docBlock->setShortDescription($reflectionDocBlock->getShortDescription());
$docBlock->setLongDescription($reflectionDocBlock->getLongDescription());
foreach ($reflectionDocBlock->getTags() as $tag) {
$docBlock->setTag(self::getTagManager()->createTagFromReflection($tag));
}
return $docBlock;
}
/**
* fromReflection() - Build a docblock generator object from a reflection object
*
* @param ReflectionDocblock $reflectionDocblock
* @return DocblockGenerator
*/
public static function fromReflection(DocBlockReflection $reflectionDocblock)
{
$docblock = new self();
$docblock->setSourceContent($reflectionDocblock->getContents());
$docblock->setSourceDirty(false);
$docblock->setShortDescription($reflectionDocblock->getShortDescription());
$docblock->setLongDescription($reflectionDocblock->getLongDescription());
foreach ($reflectionDocblock->getTags() as $tag) {
$docblock->setTag(Docblock\Tag::fromReflection($tag));
}
return $docblock;
}
public function testCreatingTagFromReflection()
{
$docreflection = new DocBlockReflection('/** @method static int method() method(int $a)');
$reflectionTag = $docreflection->getTag('method');
/** @var MethodTag $tag */
$tag = $this->tagmanager->createTagFromReflection($reflectionTag);
$this->assertInstanceOf('Zend\\Code\\Generator\\DocBlock\\Tag\\MethodTag', $tag);
$this->assertEquals(true, $tag->isStatic());
$this->assertEquals('int', $tag->getTypesAsString());
$this->assertEquals('method', $tag->getMethodName());
$this->assertEquals('method(int $a)', $tag->getDescription());
}
/**
* Retrieve method docblock reflection
*
* @return DocBlockReflection
*/
public function getDocBlock()
{
if ('' == $this->getDocComment()) {
return false;
//throw new Exception\InvalidArgumentException($this->getName() . ' does not have a DocComment');
}
$instance = new DocBlockReflection($this);
if ($this->annotationManager) {
$instance->setAnnotationManager($this->annotationManager);
}
return $instance;
}
/**
* Analyze documentation and extract annotated properties.
*
* @param string $type Normalized type name.
* @param \Zend\Code\Reflection\DocBlockReflection $block Documentation block.
*/
public function _processDocBlock($type, \Zend\Code\Reflection\DocBlockReflection $block)
{
if ($block) {
$docBlockLines = $block->getContents();
$docBlockLines = explode("\n", $docBlockLines);
foreach ($docBlockLines as $line) {
$propData = $this->_processDocLine($line);
if ($propData) {
$propName = $propData->getName();
$propType = $propData->getType();
/* skip methods specific for DataObject */
if ($propName == self::SKIP_DATA || $propName == self::SKIP_ITERATOR) {
continue;
}
$this->_registry[$type][$propName] = $propData;
$this->register($propType);
}
}
}
}
/**
* Use code reflection to create method signatures
*
* Determines the method help/description text from the function DocBlock
* comment. Determines method signatures using a combination of
* ReflectionFunction and parsing of DocBlock @param and @return values.
*
* @throws Exception\RuntimeException
* @return array
*/
protected function reflect()
{
$function = $this->reflection;
$paramCount = $function->getNumberOfParameters();
$parameters = $function->getParameters();
$scanner = new DocBlockReflection($function->getDocComment() ?: '/***/');
$helpText = $scanner->getLongDescription();
/* @var \Zend\Code\Reflection\DocBlock\Tag\ParamTag[] $paramTags */
$paramTags = $scanner->getTags('param');
/* @var \Zend\Code\Reflection\DocBlock\Tag\ReturnTag $returnTag */
$returnTag = $scanner->getTag('return');
if (empty($helpText)) {
$helpText = $scanner->getShortDescription();
if (empty($helpText)) {
$helpText = $function->getName();
}
}
$this->setDescription($helpText);
if ($returnTag) {
$return = array();
$returnDesc = $returnTag->getDescription();
foreach ($returnTag->getTypes() as $type) {
$return[] = $type;
}
} else {
$return = array('void');
$returnDesc = '';
}
$paramTypesTmp = array();
$paramDesc = array();
if (empty($paramTags)) {
foreach ($parameters as $param) {
$paramTypesTmp[] = array($param->isArray() ? 'array' : 'mixed');
$paramDesc[] = '';
}
} else {
$paramDesc = array();
foreach ($paramTags as $paramTag) {
$paramTypesTmp[] = $paramTag->getTypes();
$paramDesc[] = $paramTag->getDescription() ?: '';
}
}
// Get all param types as arrays
$nParamTypesTmp = count($paramTypesTmp);
if ($nParamTypesTmp < $paramCount) {
$start = $paramCount - $nParamTypesTmp;
for ($i = $start; $i < $paramCount; ++$i) {
$paramTypesTmp[$i] = array('mixed');
$paramDesc[$i] = '';
}
} elseif ($nParamTypesTmp != $paramCount) {
throw new Exception\RuntimeException('Variable number of arguments is not supported for services (except optional parameters). ' . 'Number of function arguments must correspond to actual number of arguments described in a docblock.');
}
$paramTypes = array();
foreach ($paramTypesTmp as $i => $param) {
if ($parameters[$i]->isOptional()) {
array_unshift($param, null);
}
$paramTypes[] = $param;
}
$this->buildSignatures($return, $returnDesc, $paramTypes, $paramDesc);
}
public function testFunctionDocBlockTags()
{
$docblock = '
/**
* Method ShortDescription
*
* @param int $one Description for one
* @param int[] Description for two
* @param string|null $three Description for three
* which spans multiple lines
* @return int[]|null Description
* @throws Exception
*/
';
$docblockReflection = new DocBlockReflection($docblock);
$paramTags = $docblockReflection->getTags('param');
$this->assertEquals(5, count($docblockReflection->getTags()));
$this->assertEquals(3, count($paramTags));
$this->assertEquals(1, count($docblockReflection->getTags('return')));
$this->assertEquals(1, count($docblockReflection->getTags('throws')));
$returnTag = $docblockReflection->getTag('return');
$this->assertInstanceOf('Zend\\Code\\Reflection\\DocBlock\\Tag\\ReturnTag', $returnTag);
$this->assertEquals('int[]', $returnTag->getType());
$this->assertEquals(array('int[]', 'null'), $returnTag->getTypes());
$this->assertEquals('Description', $returnTag->getDescription());
$throwsTag = $docblockReflection->getTag('throws');
$this->assertInstanceOf('Zend\\Code\\Reflection\\DocBlock\\Tag\\ThrowsTag', $throwsTag);
$this->assertEquals('Exception', $throwsTag->getType());
$paramTag = $paramTags[0];
$this->assertInstanceOf('Zend\\Code\\Reflection\\DocBlock\\Tag\\ParamTag', $paramTag);
$this->assertEquals('int', $paramTag->getType());
$paramTag = $paramTags[1];
$this->assertInstanceOf('Zend\\Code\\Reflection\\DocBlock\\Tag\\ParamTag', $paramTag);
$this->assertEquals('int[]', $paramTag->getType());
$paramTag = $paramTags[2];
$this->assertInstanceOf('Zend\\Code\\Reflection\\DocBlock\\Tag\\ParamTag', $paramTag);
$this->assertEquals('string', $paramTag->getType());
$this->assertEquals(array('string', 'null'), $paramTag->getTypes());
}
/**
* Get short and long description from docblock and concatenate.
*
* @param \Zend\Code\Reflection\DocBlockReflection $doc
* @return string
*/
public function getDescription(\Zend\Code\Reflection\DocBlockReflection $doc)
{
$shortDescription = $doc->getShortDescription();
$longDescription = $doc->getLongDescription();
$description = rtrim($shortDescription);
$longDescription = str_replace(["\n", "\r"], '', $longDescription);
if (!empty($longDescription) && !empty($description)) {
$description .= " ";
}
$description .= ltrim($longDescription);
return $description;
}
/**
* @param \Zend\Code\Reflection\DocBlockReflection|false $docBlock
* @return \Praxigento\Core\Reflection\Data\Method
*/
public function _processMethodDocBlock($docBlock)
{
/** @var \Praxigento\Core\Reflection\Data\Method $result */
$result = $this->_manObj->create(\Praxigento\Core\Reflection\Data\Method::class);
if ($docBlock) {
$returnAnnotations = $docBlock->getTags('return');
if (!empty($returnAnnotations)) {
/** @var \Zend\Code\Reflection\DocBlock\Tag\ReturnTag $returnTag */
$returnTag = current($returnAnnotations);
$types = $returnTag->getTypes();
$returnType = current($types);
$nullable = in_array('null', $types);
$desc = $returnTag->getDescription();
$result->setType($returnType);
$result->setIsRequired(!$nullable);
$result->setDescription($desc);
}
}
return $result;
}
/**
* Extracts the DocBlock (in parts) from the source of the stored routine.
*/
private function getDocBlockPartsSource()
{
// Get the DocBlock for the source.
$tmp = PHP_EOL;
foreach ($this->routineSourceCodeLines as $line) {
$n = preg_match('/create\\s+(procedure|function)\\s+([a-zA-Z0-9_]+)/i', $line);
if ($n) {
break;
}
$tmp .= $line;
$tmp .= PHP_EOL;
}
$phpdoc = new DocBlockReflection($tmp);
// Get the short description.
$this->docBlockPartsSource['sort_description'] = $phpdoc->getShortDescription();
// Get the long description.
$this->docBlockPartsSource['long_description'] = $phpdoc->getLongDescription();
// Get the description for each parameter of the stored routine.
foreach ($phpdoc->getTags() as $key => $tag) {
if ($tag->getName() == 'param') {
/* @var $tag ParamTag */
$this->docBlockPartsSource['parameters'][$key] = ['name' => $tag->getTypes()[0], 'description' => $tag->getDescription()];
}
}
}
/**
* Get return type tag
*
* @throws Exception\InvalidArgumentException
* @return DocBlock\Tag\ReturnTag
*/
public function getReturn()
{
$docBlock = $this->getDocBlock();
if (!$docBlock->hasTag('return')) {
throw new Exception\InvalidArgumentException('Function does not specify an @return annotation tag; cannot determine return type');
}
$tag = $docBlock->getTag('return');
$return = DocBlockReflection::factory('@return ' . $tag->getDescription());
return $return;
}
/**
* Extract method deprecation policy.
*
* Return result in the following format:<pre>
* array(
* 'removed' => true, // either 'deprecated' or 'removed' item must be specified
* 'deprecated' => true,
* 'use_resource' => 'operationName' // resource to be used instead
* 'use_method' => 'operationName' // method to be used instead
* 'use_version' => N, // version of method to be used instead
* )
* </pre>
*
* @param ReflectionMethod $methodReflection
* @return array|bool On success array with policy details; false otherwise.
* @throws LogicException If deprecation tag format is incorrect.
*/
protected function _extractDeprecationPolicy(ReflectionMethod $methodReflection)
{
$deprecationPolicy = false;
$methodDocumentation = $methodReflection->getDocComment();
if ($methodDocumentation) {
/** Zend server reflection is not able to work with annotation tags of the method. */
$docBlock = new DocBlockReflection($methodDocumentation);
$removedTag = $docBlock->getTag('apiRemoved');
$deprecatedTag = $docBlock->getTag('apiDeprecated');
if ($removedTag) {
$deprecationPolicy = array('removed' => true);
$useMethod = $removedTag->getContent();
} elseif ($deprecatedTag) {
$deprecationPolicy = array('deprecated' => true);
$useMethod = $deprecatedTag->getContent();
}
if (isset($useMethod) && is_string($useMethod) && !empty($useMethod)) {
$this->_extractDeprecationPolicyUseMethod($methodReflection, $useMethod, $deprecationPolicy);
}
}
return $deprecationPolicy;
}
/**
* Get short and long description from docblock and concatenate.
*
* @param Zend\Code\Reflection\DocBlockReflection $doc
* @return string
*/
protected function _getDescription(\Zend\Code\Reflection\DocBlockReflection $doc)
{
$shortDescription = $doc->getShortDescription();
$longDescription = $doc->getLongDescription();
$description = $shortDescription;
if ($longDescription && !empty($description)) {
$description .= "\r\n";
}
$description .= $longDescription;
return $description;
}
