UrlFilters::annotationDescription() - Code Metrics - Inspection of "composer.json: alias master as 5.0.x-dev" - apigen/ApiGen - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — 4.2-to-master ( ed215f )

by E

created 2017-04-03 23:21 UTC

UrlFilters::annotationDescription() A

↳ Parent: UrlFilters

Complexity

Conditions	2
Paths	2

Size

Total Lines	5
Code Lines	3

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	2
eloc	3
nc	2
nop	2
dl	0
loc	5
rs	9.4285
c	0
b	0
f	0

<?php declare(strict_types=1);

namespace ApiGen\Templating\Filters;

use ApiGen\Contracts\Generator\Resolvers\ElementResolverInterface;
use ApiGen\Contracts\Generator\SourceCodeHighlighter\SourceCodeHighlighterInterface;
use ApiGen\Contracts\Parser\Reflection\ClassReflectionInterface;
use ApiGen\Contracts\Parser\Reflection\ElementReflectionInterface;
use ApiGen\Contracts\Parser\Reflection\FunctionReflectionInterface;
use ApiGen\Event\ProcessDocTextEvent;
use ApiGen\Templating\Filters\Helpers\ElementLinkFactory;
use ApiGen\Templating\Filters\Helpers\LinkBuilder;
use ApiGen\Templating\Filters\Helpers\Strings;
use Latte\Runtime\Filters as LatteFilters;
use Nette\Utils\Validators;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;

final class UrlFilters extends Filters
{
    /**
     * @var SourceCodeHighlighterInterface
     */
    private $highlighter;

    /**
     * @var ElementResolverInterface
     */
    private $elementResolver;

    /**
     * @var LinkBuilder
     */
    private $linkBuilder;

    /**
     * @var ElementLinkFactory
     */
    private $elementLinkFactory;

    /**
     * @var EventDispatcherInterface
     */
    private $eventDispatcher;

    public function __construct(
        SourceCodeHighlighterInterface $highlighter,
        ElementResolverInterface $elementResolver,
        LinkBuilder $linkBuilder,
        ElementLinkFactory $elementLinkFactory,
        EventDispatcherInterface $eventDispatcher
    ) {
        $this->highlighter = $highlighter;
        $this->elementResolver = $elementResolver;
        $this->linkBuilder = $linkBuilder;
        $this->elementLinkFactory = $elementLinkFactory;
        $this->eventDispatcher = $eventDispatcher;
    }

    /**
     * Tries to parse a definition of a class/method/property/constant/function
     * and returns the appropriate link if successful.
     */
    public function resolveLink(string $definition, ElementReflectionInterface $reflectionElement): ?string
    {
        if (empty($definition)) {
            return null;
        }

        $suffix = '';
        if (substr($definition, -2) === '[]') {
            $definition = substr($definition, 0, -2);
            $suffix = '[]';
        }

        $element = $this->elementResolver->resolveElement($definition, $reflectionElement, $expectedName);
        if ($element === null || $element instanceof FunctionReflectionInterface) {
            return $expectedName;
        }

        $classes = [];
        if ($element->isDeprecated()) {
            $classes[] = 'deprecated';
        }

        $link = $this->elementLinkFactory->createForElement($element, $classes);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

$x = returnsDifferentValues($y);
if (is_array($x)) {
    // $x is an array.
}

        return '<code>' . $link . $suffix . '</code>';
    }

    public function annotation(string $value, string $name, ElementReflectionInterface $reflectionElement): string
    {
        $annotationProcessors = [
            'return' => $this->processReturnAnnotations($value, $reflectionElement),
            'throws' => $this->processThrowsAnnotations($value, $reflectionElement),
            'license' => $this->processLicenseAnnotations($value),
            'link' => $this->processLinkAnnotations($value),
            'see' => $this->processSeeAnnotations($value, $reflectionElement),
            'uses' => $this->processUsesAnnotations($value, $reflectionElement),
        ];

        if (isset($annotationProcessors[$name])) {
            return $annotationProcessors[$name];
        }

        return $this->doc($value, $reflectionElement);
    }

    /**
     * Returns links for types.
     */
    public function typeLinks(string $annotation, ElementReflectionInterface $reflectionElement): string
    {
        $links = [];

        // typehints can not contain spaces
        // valid typehint is:
        // [TYPE[|TYPE[|...]][SPACE[METHOD|PARAM][DESCRIPTION]]

        $parts = explode(' ', $annotation);

        foreach (explode('|', $parts[0]) as $type) {
            $type = $this->getTypeName($type, false);
            $links[] = $this->resolveLink($type, $reflectionElement) ?: LatteFilters::escapeHtml(ltrim($type, '\\'));
        }

        return implode('|', $links);
    }

    public function annotationDescription(string $annotation, ElementReflectionInterface $reflectionElement): string
    {
        $description = trim(strpbrk($annotation, "\n\r\t $")) ?: $annotation;
        return $this->doc($description, $reflectionElement);
    }

    public function description(ElementReflectionInterface $element): string
    {
        $long = $element->getDescription();

        // Merge lines
        $long = preg_replace_callback('~(?:<(code|pre)>.+?</\1>)|([^<]*)~s', function ($matches) {
            return ! empty($matches[2])
                ? preg_replace('~\n(?:(\s+\n){2,})+~', ' ', $matches[2])
                : $matches[0];
        }, $long);

        return $this->doc($long, $element);
    }

    public function doc(string $text, ElementReflectionInterface $reflectionElement): string
    {
        $text = $this->resolveInternalAnnotation($text);

        $processDocTextEvent = new ProcessDocTextEvent($text, $reflectionElement);
        $this->eventDispatcher->dispatch(ProcessDocTextEvent::class, $processDocTextEvent);

        return $this->resolveLinkAndSeeAnnotation($processDocTextEvent->getText(), $reflectionElement);
    }

    private function resolveInternalAnnotation(string $text): string
    {
        $pattern = '~\\{@(\\w+)(?:(?:\\s+((?>(?R)|[^{}]+)*)\\})|\\})~';
        return preg_replace_callback($pattern, function ($matches) {
            if ($matches[1] !== 'internal') {
                return $matches[0];
            }

            return '';
        }, $text);
    }

    private function resolveLinkAndSeeAnnotation(string $text, ElementReflectionInterface $reflectionElement): string
    {
        return preg_replace_callback('~{@(?:link|see)\\s+([^}]+)}~', function ($matches) use ($reflectionElement) {
            [$url, $description] = Strings::split($matches[1]);


            $link = $this->resolveLink($matches[1], $reflectionElement);
            if ($link) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
                return $link;
            }

            if (Validators::isUri($url)) {
                return $this->linkBuilder->build($url, $description ?: $url);
            }

            return $matches[1];
        }, $text);
    }

    public function highlightPhp(string $source, ElementReflectionInterface $reflectionElement): string
    {
        return $this->resolveLink($this->getTypeName($source), $reflectionElement)
            ?: $this->highlighter->highlight((string) $source);
    }

    public function highlightValue(string $definition, ElementReflectionInterface $reflectionElement): string
    {
        return $this->highlightPhp(preg_replace('~^(?:[ ]{4}|\t)~m', '', $definition), $reflectionElement);
    }

    private function processReturnAnnotations(string $value, ElementReflectionInterface $reflectionElement): string
    {
        $description = $this->getDescriptionFromValue($value, $reflectionElement);
        $typeLinks = $this->typeLinks($value, $reflectionElement);
        return $typeLinks . $description;
    }

    private function processThrowsAnnotations(string $value, ElementReflectionInterface $elementReflection): string
    {
        $description = $this->getDescriptionFromValue($value, $elementReflection);
        $typeLinks = $this->typeLinks($value, $elementReflection);
        return $typeLinks . $description;
    }

    /**
     * @param mixed $value
     * @param ElementReflectionInterface $elementReflection
     */
    private function getDescriptionFromValue($value, ElementReflectionInterface $elementReflection): string
    {
        $description = (string) trim((string) strpbrk($value, "\n\r\t $")) ?: null;
        if ($description) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
            $description = '<br>' . $this->doc($description, $elementReflection);
        }

        return (string) $description;
    }

    private function processLicenseAnnotations(string $value): string
    {
        [$url, $description] = Strings::split($value);

        return $this->linkBuilder->build($url, $description ?: $url);
    }

    private function processLinkAnnotations(string $value): string
    {
        [$url, $description] = Strings::split($value);

        if (Validators::isUrl($url)) {
            return $this->linkBuilder->build($url, $description ?: $url);
        }

        return '';
    }

    private function processSeeAnnotations(string $value, ElementReflectionInterface $reflectionElement): string
    {
        $doc = [];
        foreach (preg_split('~\\s*,\\s*~', $value) as $link) {
            if ($this->elementResolver->resolveElement($link, $reflectionElement) !== null) {
                $doc[] = $this->typeLinks($link, $reflectionElement);
            } else {
                $doc[] = $this->doc($link, $reflectionElement);
            }
        }

        return implode(', ', $doc);
    }

    private function processUsesAnnotations(string $value, ElementReflectionInterface $reflectionElement): ?string
    {
        [$link, $description] = Strings::split($value);

        $separator = $reflectionElement instanceof ClassReflectionInterface || ! $description ? ' ' : '<br>';
        if ($this->elementResolver->resolveElement($link, $reflectionElement) !== null) {
            $value = $this->typeLinks($link, $reflectionElement) . $separator . $description;
            return trim($value);
        }

        return null;
    }
}


1			<?php declare(strict_types=1);
2
3			namespace ApiGen\Templating\Filters;
4
5			use ApiGen\Contracts\Generator\Resolvers\ElementResolverInterface;
6			use ApiGen\Contracts\Generator\SourceCodeHighlighter\SourceCodeHighlighterInterface;
7			use ApiGen\Contracts\Parser\Reflection\ClassReflectionInterface;
8			use ApiGen\Contracts\Parser\Reflection\ElementReflectionInterface;
9			use ApiGen\Contracts\Parser\Reflection\FunctionReflectionInterface;
10			use ApiGen\Event\ProcessDocTextEvent;
11			use ApiGen\Templating\Filters\Helpers\ElementLinkFactory;
12			use ApiGen\Templating\Filters\Helpers\LinkBuilder;
13			use ApiGen\Templating\Filters\Helpers\Strings;
14			use Latte\Runtime\Filters as LatteFilters;
15			use Nette\Utils\Validators;
16			use Symfony\Component\EventDispatcher\EventDispatcherInterface;
17
18			final class UrlFilters extends Filters
19			{
20			/**
21			* @var SourceCodeHighlighterInterface
22			*/
23			private $highlighter;
24
25			/**
26			* @var ElementResolverInterface
27			*/
28			private $elementResolver;
29
30			/**
31			* @var LinkBuilder
32			*/
33			private $linkBuilder;
34
35			/**
36			* @var ElementLinkFactory
37			*/
38			private $elementLinkFactory;
39
40			/**
41			* @var EventDispatcherInterface
42			*/
43			private $eventDispatcher;
44
45			public function __construct(
46			SourceCodeHighlighterInterface $highlighter,
47			ElementResolverInterface $elementResolver,
48			LinkBuilder $linkBuilder,
49			ElementLinkFactory $elementLinkFactory,
50			EventDispatcherInterface $eventDispatcher
51			) {
52			$this->highlighter = $highlighter;
53			$this->elementResolver = $elementResolver;
54			$this->linkBuilder = $linkBuilder;
55			$this->elementLinkFactory = $elementLinkFactory;
56			$this->eventDispatcher = $eventDispatcher;
57			}
58
59			/**
60			* Tries to parse a definition of a class/method/property/constant/function
61			* and returns the appropriate link if successful.
62			*/
63			public function resolveLink(string $definition, ElementReflectionInterface $reflectionElement): ?string
64			{
65			if (empty($definition)) {
66			return null;
67			}
68
69			$suffix = '';
70			if (substr($definition, -2) === '[]') {
71			$definition = substr($definition, 0, -2);
72			$suffix = '[]';
73			}
74
75			$element = $this->elementResolver->resolveElement($definition, $reflectionElement, $expectedName);
76			if ($element === null \|\| $element instanceof FunctionReflectionInterface) {
77			return $expectedName;
78			}
79
80			$classes = [];
81			if ($element->isDeprecated()) {
82			$classes[] = 'deprecated';
83			}
84
85			$link = $this->elementLinkFactory->createForElement($element, $classes);
			0 ignored issues – show Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report It seems like `$element` defined by `$this->elementResolver->...Element, $expectedName)` on line `75` can also be of type `boolean`; however, `ApiGen\Templating\Filter...ory::createForElement()` does only seem to accept `object<ApiGen\Contracts\...entReflectionInterface>`, maybe add an additional type check? If a method or function can return multiple different values and unless you are sure that you only can receive a single value in this context, we recommend to add an additional type check: /** * @return array\|string */ function returnsDifferentValues($x) { if ($x) { return 'foo'; } return array(); } $x = returnsDifferentValues($y); if (is_array($x)) { // $x is an array. } If this a common case that PHP Analyzer should handle natively, please let us know by opening an issue. Loading history...
86
87			return '<code>' . $link . $suffix . '</code>';
88			}
89
90			public function annotation(string $value, string $name, ElementReflectionInterface $reflectionElement): string
91			{
92			$annotationProcessors = [
93			'return' => $this->processReturnAnnotations($value, $reflectionElement),
94			'throws' => $this->processThrowsAnnotations($value, $reflectionElement),
95			'license' => $this->processLicenseAnnotations($value),
96			'link' => $this->processLinkAnnotations($value),
97			'see' => $this->processSeeAnnotations($value, $reflectionElement),
98			'uses' => $this->processUsesAnnotations($value, $reflectionElement),
99			];
100
101			if (isset($annotationProcessors[$name])) {
102			return $annotationProcessors[$name];
103			}
104
105			return $this->doc($value, $reflectionElement);
106			}
107
108			/**
109			* Returns links for types.
110			*/
111			public function typeLinks(string $annotation, ElementReflectionInterface $reflectionElement): string
112			{
113			$links = [];
114
115			// typehints can not contain spaces
116			// valid typehint is:
117			// [TYPE[\|TYPE[\|...]][SPACE[METHOD\|PARAM][DESCRIPTION]]
			0 ignored issues – show Unused Code Comprehensibility introduced 2016-10-11 12:36 UTC by Report Bug Copy Issue Report `69%` of this comment could be valid code. Did you maybe forget this after debugging? Sometimes obsolete code just ends up commented out instead of removed. In this case it is better to remove the code once you have checked you do not need it. The code might also have been commented out for debugging purposes. In this case it is vital that someone uncomments it again or your project may behave in very unexpected ways in production. This check looks for comments that seem to be mostly valid code and reports them. Loading history...
118			$parts = explode(' ', $annotation);
119
120			foreach (explode('\|', $parts[0]) as $type) {
121			$type = $this->getTypeName($type, false);
122			$links[] = $this->resolveLink($type, $reflectionElement) ?: LatteFilters::escapeHtml(ltrim($type, '\\'));
123			}
124
125			return implode('\|', $links);
126			}
127
128			public function annotationDescription(string $annotation, ElementReflectionInterface $reflectionElement): string
129			{
130			$description = trim(strpbrk($annotation, "\n\r\t $")) ?: $annotation;
131			return $this->doc($description, $reflectionElement);
132			}
133
134			public function description(ElementReflectionInterface $element): string
135			{
136			$long = $element->getDescription();
137
138			// Merge lines
139			$long = preg_replace_callback('~(?:<(code\|pre)>.+?</\1>)\|([^<]*)~s', function ($matches) {
140			return ! empty($matches[2])
141			? preg_replace('~\n(?:(\s+\n){2,})+~', ' ', $matches[2])
142			: $matches[0];
143			}, $long);
144
145			return $this->doc($long, $element);
146			}
147
148			public function doc(string $text, ElementReflectionInterface $reflectionElement): string
149			{
150			$text = $this->resolveInternalAnnotation($text);
151
152			$processDocTextEvent = new ProcessDocTextEvent($text, $reflectionElement);
153			$this->eventDispatcher->dispatch(ProcessDocTextEvent::class, $processDocTextEvent);
154
155			return $this->resolveLinkAndSeeAnnotation($processDocTextEvent->getText(), $reflectionElement);
156			}
157
158			private function resolveInternalAnnotation(string $text): string
159			{
160			$pattern = '~\\{@(\\w+)(?:(?:\\s+((?>(?R)\|[^{}]+)*)\\})\|\\})~';
161			return preg_replace_callback($pattern, function ($matches) {
162			if ($matches[1] !== 'internal') {
163			return $matches[0];
164			}
165
166			return '';
167			}, $text);
168			}
169
170			private function resolveLinkAndSeeAnnotation(string $text, ElementReflectionInterface $reflectionElement): string
171			{
172			return preg_replace_callback('~{@(?:link\|see)\\s+([^}]+)}~', function ($matches) use ($reflectionElement) {
173			[$url, $description] = Strings::split($matches[1]);
			0 ignored issues – show Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$url` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history... Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$description` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history...
174
175			$link = $this->resolveLink($matches[1], $reflectionElement);
176			if ($link) {
			0 ignored issues – show Bug Best Practice introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The expression `$link` of type `null\|string` is loosely compared to `true`; this is ambiguous if the string can be empty. You might want to explicitly use `!== null` instead. In PHP, under loose comparison (like `==`, or `!=`, or `switch` conditions), values of different types might be equal. For `string` values, the empty string `''` is a special case, in particular the following results might be unexpected: '' == false // true '' == null // true 'ab' == false // false 'ab' == null // false // It is often better to use strict comparison '' === false // false '' === null // false Loading history...
177			return $link;
178			}
179
180			if (Validators::isUri($url)) {
181			return $this->linkBuilder->build($url, $description ?: $url);
182			}
183
184			return $matches[1];
185			}, $text);
186			}
187
188			public function highlightPhp(string $source, ElementReflectionInterface $reflectionElement): string
189			{
190			return $this->resolveLink($this->getTypeName($source), $reflectionElement)
191			?: $this->highlighter->highlight((string) $source);
192			}
193
194			public function highlightValue(string $definition, ElementReflectionInterface $reflectionElement): string
195			{
196			return $this->highlightPhp(preg_replace('~^(?:[ ]{4}\|\t)~m', '', $definition), $reflectionElement);
197			}
198
199			private function processReturnAnnotations(string $value, ElementReflectionInterface $reflectionElement): string
200			{
201			$description = $this->getDescriptionFromValue($value, $reflectionElement);
202			$typeLinks = $this->typeLinks($value, $reflectionElement);
203			return $typeLinks . $description;
204			}
205
206			private function processThrowsAnnotations(string $value, ElementReflectionInterface $elementReflection): string
207			{
208			$description = $this->getDescriptionFromValue($value, $elementReflection);
209			$typeLinks = $this->typeLinks($value, $elementReflection);
210			return $typeLinks . $description;
211			}
212
213			/**
214			* @param mixed $value
215			* @param ElementReflectionInterface $elementReflection
216			*/
217			private function getDescriptionFromValue($value, ElementReflectionInterface $elementReflection): string
218			{
219			$description = (string) trim((string) strpbrk($value, "\n\r\t $")) ?: null;
220			if ($description) {
			0 ignored issues – show Bug Best Practice introduced 2015-11-29 18:26 UTC by Report Bug Copy Issue Report The expression `$description` of type `string\|null` is loosely compared to `true`; this is ambiguous if the string can be empty. You might want to explicitly use `!== null` instead. In PHP, under loose comparison (like `==`, or `!=`, or `switch` conditions), values of different types might be equal. For `string` values, the empty string `''` is a special case, in particular the following results might be unexpected: '' == false // true '' == null // true 'ab' == false // false 'ab' == null // false // It is often better to use strict comparison '' === false // false '' === null // false Loading history...
221			$description = '<br>' . $this->doc($description, $elementReflection);
222			}
223
224			return (string) $description;
225			}
226
227			private function processLicenseAnnotations(string $value): string
228			{
229			[$url, $description] = Strings::split($value);
			0 ignored issues – show Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$url` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history... Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$description` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history...
230			return $this->linkBuilder->build($url, $description ?: $url);
231			}
232
233			private function processLinkAnnotations(string $value): string
234			{
235			[$url, $description] = Strings::split($value);
			0 ignored issues – show Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$url` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history... Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$description` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history...
236			if (Validators::isUrl($url)) {
237			return $this->linkBuilder->build($url, $description ?: $url);
238			}
239
240			return '';
241			}
242
243			private function processSeeAnnotations(string $value, ElementReflectionInterface $reflectionElement): string
244			{
245			$doc = [];
246			foreach (preg_split('~\\s,\\s~', $value) as $link) {
247			if ($this->elementResolver->resolveElement($link, $reflectionElement) !== null) {
248			$doc[] = $this->typeLinks($link, $reflectionElement);
249			} else {
250			$doc[] = $this->doc($link, $reflectionElement);
251			}
252			}
253
254			return implode(', ', $doc);
255			}
256
257			private function processUsesAnnotations(string $value, ElementReflectionInterface $reflectionElement): ?string
258			{
259			[$link, $description] = Strings::split($value);
			0 ignored issues – show Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$link` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history... Bug introduced 2017-04-03 23:27 UTC by Report Bug Copy Issue Report The variable `$description` does not exist. Did you forget to declare it? This check marks access to variables or properties that have not been declared yet. While PHP has no explicit notion of declaring a variable, accessing it before a value is assigned to it is most likely a bug. Loading history...
260			$separator = $reflectionElement instanceof ClassReflectionInterface \|\| ! $description ? ' ' : '<br>';
261			if ($this->elementResolver->resolveElement($link, $reflectionElement) !== null) {
262			$value = $this->typeLinks($link, $reflectionElement) . $separator . $description;
263			return trim($value);
264			}
265
266			return null;
267			}
268			}
269

apigen / ApiGen

GitHub Access Token became invalid

Push — 4.2-to-master ( ed215f )

UrlFilters::annotationDescription() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like