/**
* Filter Descriptor with based on visibility.
*
* @param DescriptorAbstract $value
*
* @return DescriptorAbstract|null
*/
public function filter($value)
{
if ($value instanceof VisibilityInterface && !$this->builder->isVisibilityAllowed($value->getVisibility())) {
return null;
}
return $value;
}
/**
* Retrieves the File Descriptor from the given element.
*
* @param DescriptorAbstract $element
*
* @throws \UnexpectedValueException if the provided element does not have a file associated with it.
*
* @return FileDescriptor
*/
protected function getFileDescriptor($element)
{
$fileDescriptor = $element instanceof FileDescriptor ? $element : $element->getFile();
if (!$fileDescriptor instanceof FileDescriptor) {
throw new \UnexpectedValueException('An element should always have a file associated with it');
}
return $fileDescriptor;
}
/**
* Generates a URL from the given node or returns false if unable.
*
* @param DescriptorAbstract $node
*
* @return string|false
*/
public function __invoke($node)
{
$name = str_replace('\\', '.', ltrim($node->getFullyQualifiedStructuralElementName(), '\\'));
// convert root namespace to default; default is a keyword and no namespace CAN be named as such
if ($name === '') {
$name = 'default';
}
return '/packages/' . $name . '.html';
}
/**
* Overrides the name and namespace of an element with a separated version of the class name.
*
* If a class is separated by underscores than the last part is set as name and the first parts are set as
* namespace with the namespace separator instead of an underscore.
*
* @param DescriptorAbstract $value
*
* @return DescriptorAbstract|null
*/
public function filter($value)
{
if ($value) {
$namespace = $value->getNamespace() == '' ? '\\' . $this->namespacePrefix : $value->getNamespace();
$value->setNamespace($this->namespaceFromLegacyNamespace($namespace, $value->getName()));
$value->setName($this->classNameFromLegacyNamespace($value->getName()));
}
return $value;
}
/**
* Assemble DocBlock.
*
* @param DocBlock|null $docBlock
* @param DescriptorAbstract $target
*
* @return void
*/
protected function assembleDocBlock($docBlock, $target)
{
if (!$docBlock) {
return;
}
$target->setSummary($docBlock->getShortDescription());
$target->setDescription($docBlock->getLongDescription()->getContents());
/** @var DocBlock\Tag $tag */
foreach ($docBlock->getTags() as $tag) {
$tagDescriptor = $this->builder->buildDescriptor($tag);
// allow filtering of tags
if (!$tagDescriptor) {
continue;
}
$target->getTags()->get($tag->getName(), new Collection())->add($tagDescriptor);
}
}
/**
* Initializes a new file descriptor with the given hash of its contents.
*
* @param string $hash An MD5 hash of the contents if this file.
*/
public function __construct($hash)
{
parent::__construct();
$this->setHash($hash);
$this->setNamespaceAliases(new Collection());
$this->setIncludes(new Collection());
$this->setConstants(new Collection());
$this->setFunctions(new Collection());
$this->setClasses(new Collection());
$this->setInterfaces(new Collection());
$this->setTraits(new Collection());
$this->setMarkers(new Collection());
}
/**
* If the ProjectDescriptor's settings allow internal tags then return the Descriptor, otherwise null to filter it.
*
* @param DescriptorAbstract $value
*
* @return DescriptorAbstract|null
*/
public function filter($value)
{
$isInternalAllowed = $this->builder->isVisibilityAllowed(Settings::VISIBILITY_INTERNAL);
if ($isInternalAllowed) {
$value->setDescription(preg_replace('/{@internal\\ (.+)}}/', '$1', $value->getDescription()));
return $value;
}
// remove inline @internal tags
$value->setDescription(preg_replace('/{@internal\\ .+}}/', '', $value->getDescription()));
// if internal elements are not allowed; filter this element
if ($value->getTags()->get('internal')) {
return null;
}
return $value;
}
/**
* Replaces the example tags in the description with the contents of the found example.
*
* @param DescriptorAbstract $element
*
* @return string
*/
protected function replaceInlineExamples(DescriptorAbstract $element)
{
$description = $element->getDescription();
$matches = array();
if (!$description || !preg_match_all('/\\{@example\\s(.+?)\\}/', $description, $matches) || count($matches[0]) < 1) {
return $description;
}
$matched = array();
foreach ($matches[0] as $index => $match) {
if (isset($matched[$match])) {
continue;
}
$matched[$match] = true;
$exampleReflector = new ExampleTag('example', $matches[1][$index]);
$example = $this->exampleAssembler->create($exampleReflector);
$replacement = '`' . $example->getExample() . '`';
if ($example->getDescription()) {
$replacement = '*' . $example->getDescription() . '*' . $replacement;
}
$description = str_replace($match, $replacement, $description);
}
return $description;
}
/**
* Adds each tag to the $xml_node.
*
* @param \DOMElement $xml_node
* @param DescriptorAbstract $element
*
* @return void
*/
protected function addTags(\DOMElement $xml_node, $element)
{
foreach ($element->getTags() as $tagGroup) {
if ($tagGroup === null) {
continue;
}
foreach ($tagGroup as $tag) {
$this->buildDocBlockTag($xml_node, $tag, $element);
}
}
}
/**
* @covers phpDocumentor\Descriptor\DescriptorAbstract::__toString
*/
public function testToString()
{
$this->fixture->setFullyQualifiedStructuralElementName('fqn');
$this->assertSame('fqn', (string) $this->fixture);
}
/**
* Normalizes the given FQSEN as if the context marker represents a class/interface/trait as parent.
*
* @param string $fqsen
* @param DescriptorAbstract $container
*
* @return string
*/
protected function getTypeWithNamespaceAsContext($fqsen, DescriptorAbstract $container)
{
$namespace = $container instanceof NamespaceDescriptor ? $container : $container->getNamespace();
$fqnn = $namespace instanceof NamespaceDescriptor ? $namespace->getFullyQualifiedStructuralElementName() : $namespace;
return str_replace(self::CONTEXT_MARKER . '::', $fqnn . '\\', $fqsen);
}
/**
* Creates a DocBlock context containing the namespace and aliases for the current descriptor.
*
* @return Context
*/
private function createDocBlockContext()
{
$file = $this->descriptor->getFile();
$namespaceAliases = $file ? $file->getNamespaceAliases()->getAll() : array();
return new Context($this->descriptor->getNamespace(), $namespaceAliases);
}
/**
* Adds the 'inherited_from' tag when a Descriptor inherits from another Descriptor.
*
* @param \DOMElement $docBlock
* @param DescriptorAbstract $descriptor
*
* @return void
*/
protected function addInheritedFromTag(\DOMElement $docBlock, $descriptor)
{
$parentElement = $descriptor->getInheritedElement();
if (!$parentElement instanceof $descriptor) {
return;
}
$child = new \DOMElement('tag');
$docBlock->appendChild($child);
$rule = $this->router->match($parentElement);
$child->setAttribute('name', 'inherited_from');
$child->setAttribute('description', $parentElement->getFullyQualifiedStructuralElementName());
$child->setAttribute('refers', $parentElement->getFullyQualifiedStructuralElementName());
$child->setAttribute('link', $rule ? $rule->generate($parentElement) : '');
}
/**
* This implements testing of the protected buildDocBlock method
*
* @param DescriptorAbstract $descriptor
* @return void
*/
protected function implementProtectedBuildDocBlock(DescriptorAbstract $descriptor)
{
$descriptor->shouldReceive('getLine')->andReturn(666);
$descriptor->shouldReceive('getPackage')->andReturn('myPackage');
$descriptor->shouldReceive('getSummary')->andReturn('my summary');
$descriptor->shouldReceive('getDescription')->andReturn('my description');
$descriptor->shouldReceive('getTags')->andReturn(array());
}
/**
* Describes when a descriptor has tags.
*
* @param DescriptorAbstract|m\MockInterface $descriptor
* @param array $tags
*
* @return void
*/
protected function whenDescriptorHasTags($descriptor, $tags)
{
$descriptor->shouldReceive('getTags')->andReturn($tags);
}
/**
* Returns the file associated with the parent class, interface or trait when inside a container.
*
* @return FileDescriptor
*/
public function getFile()
{
return parent::getFile() ?: $this->getParent()->getFile();
}
/**
* Retrieves a key for the index for the provided element.
*
* @param DescriptorAbstract $element
*
* @return string
*/
protected function getIndexKey($element)
{
$key = $element->getFullyQualifiedStructuralElementName();
// properties should have an additional $ before the property name
if ($element instanceof PropertyInterface) {
list($fqcn, $propertyName) = explode('::', $key);
$key = $fqcn . '::$' . $propertyName;
}
return $key;
}
/**
* Generates a URL from the given node or returns false if unable.
*
* @param DescriptorAbstract $node
*
* @return string|false
*/
public function __invoke($node)
{
return '/classes/' . str_replace('\\', '.', ltrim($node->getFullyQualifiedStructuralElementName(), '\\')) . '.html';
}
/**
* @param DescriptorAbstract $descriptor
* @param string $description
*/
protected function givenDescriptorHasTodoTagWithDescription($descriptor, $description)
{
$todoTag = new TagDescriptor('todo');
$todoTag->setDescription($description);
$todoTags = $descriptor->getTags()->get('todo', array());
$todoTags[] = $todoTag;
$descriptor->getTags()->set('todo', $todoTags);
}
/**
* Uses the currently selected node and transformation to assemble the destination path for the file.
*
* @param DescriptorAbstract $node
* @param Transformation $transformation
*
* @return string|false returns the destination location or false if generation should be aborted.
*/
protected function getDestinationPath($node, Transformation $transformation)
{
$this->destinationPath = $this->destinationPath ?: sys_get_temp_dir() . DIRECTORY_SEPARATOR . md5($node->getName());
return $this->destinationPath;
}
/**
* Generates a URL from the given node or returns false if unable.
*
* @param DescriptorAbstract $node
*
* @return string|false
*/
public function __invoke($node)
{
$name = str_replace(array('/', '\\'), '.', ltrim($node->getPath(), '/'));
return '/files/' . $name . '.html';
}
