Completed
Push — develop ( 48a3ec...fa4cb4 )
by Mike
05:54
created

Compiler/Pass/ExampleTagsEnricher.php (1 issue)

Labels
Severity

Upgrade to new PHP Analysis Engine

These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more

1
<?php
2
declare(strict_types=1);
3
4
/**
5
 * This file is part of phpDocumentor.
6
 *
7
 * For the full copyright and license information, please view the LICENSE
8
 * file that was distributed with this source code.
9
 *
10
 * @author    Mike van Riel <[email protected]>
11
 * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
12
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
13
 * @link      http://phpdoc.org
14
 */
15
16
namespace phpDocumentor\Compiler\Pass;
17
18
use phpDocumentor\Compiler\CompilerPassInterface;
19
use phpDocumentor\Descriptor\Builder\Reflector\Tags\ExampleAssembler;
20
use phpDocumentor\Descriptor\DescriptorAbstract;
21
use phpDocumentor\Descriptor\ProjectDescriptor;
22
use phpDocumentor\Reflection\DocBlock\ExampleFinder;
23
use phpDocumentor\Reflection\DocBlock\Tags\Example;
24
25
/**
26
 * This index builder collects all examples from tags and inserts them into the example index.
27
 */
28
class ExampleTagsEnricher implements CompilerPassInterface
29
{
30
    const COMPILER_PRIORITY = 9002;
31
32
    /** @var ExampleAssembler */
33
    private $exampleAssembler;
34
35
    /**
36
     * Initializes this compiler pass with its dependencies.
37
     *
38
     * @param ExampleFinder $finder Finds examples in several directories.
39
     */
40 4
    public function __construct(ExampleFinder $finder)
41
    {
42 4
        $this->exampleAssembler = new ExampleAssembler($finder);
43 4
    }
44
45 1
    public function getDescription(): string
46
    {
47 1
        return 'Enriches inline example tags with their sources';
48
    }
49
50 4
    public function execute(ProjectDescriptor $project): void
51
    {
52 4
        $elements = $project->getIndexes()->get('elements');
53
54
        /** @var DescriptorAbstract $element */
55 4
        foreach ($elements as $element) {
56 4
            $element->setDescription($this->replaceInlineExamples($element));
57
        }
58 4
    }
59
60
    /**
61
     * Replaces the example tags in the description with the contents of the found example.
62
     */
63 4
    protected function replaceInlineExamples(DescriptorAbstract $element): string
64
    {
65 4
        $description = $element->getDescription();
66 4
        $matches = [];
67
68 4
        if (! $description
69 4
            || ! preg_match_all('/\{@example\s(.+?)\}/', $description, $matches)
70 4
            || count($matches[0]) < 1
71
        ) {
72 1
            return $description;
73
        }
74
75 3
        $matched = [];
76 3
        foreach ($matches[0] as $index => $match) {
77 3
            if (isset($matched[$match])) {
78 1
                continue;
79
            }
80
81 3
            $matched[$match] = true;
82 3
            $exampleReflector = Example::create($matches[1][$index]);
83
84 3
            $example = $this->exampleAssembler->create($exampleReflector);
0 ignored issues
show
It seems like $exampleReflector defined by \phpDocumentor\Reflectio...te($matches[1][$index]) on line 82 can be null; however, phpDocumentor\Descriptor...mpleAssembler::create() does not accept null, maybe add an additional type check?

Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code:

/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}
Loading history...
85
86 3
            $replacement = '`' . $example->getExample() . '`';
87 3
            if ($example->getDescription()) {
88 1
                $replacement = '*' . $example->getDescription() . '*' . $replacement;
89
            }
90
91 3
            $description = str_replace($match, $replacement, $description);
92
        }
93
94 3
        return $description;
95
    }
96
}
97