DocBlockFactory::create() - Code Metrics - Inspection of "Unit tests fixed" - phpDocumentor/ReflectionDocBlock - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Pull Request — master (#102)

by Aleksei

created 2017-07-13 10:12 UTC

DocBlockFactory::create() B

↳ Parent: DocBlockFactory

Complexity

Conditions	5
Paths	5

Size

Total Lines	32
Code Lines	20

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	21
CRAP Score	5.0164

Importance

Changes

Metric	Value
dl	0
loc	32
ccs	21
cts	23
cp	0.913
rs	8.439
c	0
b	0
f	0
cc	5
eloc	20
nc	5
nop	3
crap	5.0164

<?php
/**
 * This file is part of phpDocumentor.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 *
 * @copyright 2010-2015 Mike van Riel<[email protected]>
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
 * @link      http://phpdoc.org
 */

namespace phpDocumentor\Reflection;

use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
use phpDocumentor\Reflection\DocBlock\StandardTagFactory;
use phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock\TagFactory;
use Webmozart\Assert\Assert;

final class DocBlockFactory implements DocBlockFactoryInterface

{
    /** @var DocBlock\DescriptionFactory */
    private $descriptionFactory;

    /** @var DocBlock\TagFactory */
    private $tagFactory;

    /**
     * Initializes this factory with the required subcontractors.
     *
     * @param DescriptionFactory $descriptionFactory
     * @param TagFactory         $tagFactory
     */
    public function __construct(DescriptionFactory $descriptionFactory, TagFactory $tagFactory)
    {
        $this->descriptionFactory = $descriptionFactory;
        $this->tagFactory = $tagFactory;
    }

    /**
     * Factory method for easy instantiation.
     *
     * @param string[] $additionalTags
     *
     * @return DocBlockFactory
     */
    public static function createInstance(array $additionalTags = [])
    {
        $fqsenResolver = new FqsenResolver();
        $tagFactory = new StandardTagFactory($fqsenResolver);
        $descriptionFactory = new DescriptionFactory($tagFactory);

        $tagFactory->addService($descriptionFactory);
        $tagFactory->addService(new TypeResolver($fqsenResolver));

        $docBlockFactory = new self($descriptionFactory, $tagFactory);
        foreach ($additionalTags as $tagName => $tagHandler) {
            $docBlockFactory->registerTagHandler($tagName, $tagHandler);
        }

        return $docBlockFactory;
    }

    /**
     * @param object|string $docblock A string containing the DocBlock to parse or an object supporting the
     *                                getDocComment method (such as a ReflectionClass object).
     * @param Types\Context $context
     * @param Location      $location
     *
     * @return DocBlock
     */
    public function create($docblock, Types\Context $context = null, Location $location = null)
    {
        if (is_object($docblock)) {
            if (!method_exists($docblock, 'getDocComment')) {
                $exceptionMessage = 'Invalid object passed; the given object must support the getDocComment method';
                throw new \InvalidArgumentException($exceptionMessage);
            }

            $docblock = $docblock->getDocComment();
        }

        Assert::stringNotEmpty($docblock);

        if ($context === null) {
            $context = new Types\Context('');
        }

        $parts = $this->splitDocBlock($this->stripDocComment($docblock));
        list($templateMarker, $summary, $description, $tags) = $parts;

        return new DocBlock(
            $summary,
            $description ? $this->descriptionFactory->create($description, $context) : null,
            array_filter($this->parseTagBlock($tags, $context), function($tag) {

                return $tag instanceof Tag;
            }),
            $context,
            $location,
            $templateMarker === '#@+',
            $templateMarker === '#@-'
        );
    }

    public function registerTagHandler($tagName, $handler)
    {
        $this->tagFactory->registerTagHandler($tagName, $handler);
    }

    /**
     * Strips the asterisks from the DocBlock comment.
     *
     * @param string $comment String containing the comment text.
     *
     * @return string
     */
    private function stripDocComment($comment)
    {
        $comment = trim(preg_replace('#[ \t]*(?:\/\*\*|\*\/|\*)?[ \t]{0,1}(.*)?#u', '$1', $comment));

        // reg ex above is not able to remove */ from a single line docblock
        if (substr($comment, -2) == '*/') {
            $comment = trim(substr($comment, 0, -2));
        }

        return str_replace(array("\r\n", "\r"), "\n", $comment);
    }

    /**
     * Splits the DocBlock into a template marker, summary, description and block of tags.
     *
     * @param string $comment Comment to split into the sub-parts.
     *
     * @author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.
     * @author Mike van Riel <[email protected]> for extending the regex with template marker support.
     *
     * @return string[] containing the template marker (if any), summary, description and a string containing the tags.
     */
    private function splitDocBlock($comment)
    {
        // Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
        // method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
        // performance impact of running a regular expression
        if (strpos($comment, '@') === 0) {
            return array('', '', '', $comment);
        }

        // clears all extra horizontal whitespace from the line endings to prevent parsing issues
        $comment = preg_replace('/\h*$/Sum', '', $comment);

        /*
         * Splits the docblock into a template marker, summary, description and tags section.
         *
         * - The template marker is empty, #@+ or #@- if the DocBlock starts with either of those (a newline may
         *   occur after it and will be stripped).
         * - The short description is started from the first character until a dot is encountered followed by a
         *   newline OR two consecutive newlines (horizontal whitespace is taken into account to consider spacing
         *   errors). This is optional.
         * - The long description, any character until a new line is encountered followed by an @ and word
         *   characters (a tag). This is optional.
         * - Tags; the remaining characters
         *
         * Big thanks to RichardJ for contributing this Regular Expression
         */
        preg_match(
            '/
            \A
            # 1. Extract the template marker
            (?:(\#\@\+|\#\@\-)\n?)?

            # 2. Extract the summary
            (?:
              (?! @\pL ) # The summary may not start with an @
              (
                [^\n.]+
                (?:
                  (?! \. \n | \n{2} )     # End summary upon a dot followed by newline or two newlines
                  [\n.] (?! [ \t]* @\pL ) # End summary when an @ is found as first character on a new line
                  [^\n.]+                 # Include anything else
                )*
                \.?
              )?
            )

            # 3. Extract the description
            (?:
              \s*        # Some form of whitespace _must_ precede a description because a summary must be there
              (?! @\pL ) # The description may not start with an @
              (
                [^\n]+
                (?: \n+
                  (?! [ \t]* @\pL ) # End description when an @ is found as first character on a new line
                  [^\n]+            # Include anything else
                )*
              )
            )?

            # 4. Extract the tags (anything that follows)
            (\s+ [\s\S]*)? # everything that follows
            /ux',
            $comment,
            $matches
        );
        array_shift($matches);

        while (count($matches) < 4) {
            $matches[] = '';
        }

        return $matches;
    }

    /**
     * Creates the tag objects.
     *
     * @param string $tags Tag block to parse.
     * @param Types\Context $context Context of the parsed Tag
     *
     * @return DocBlock\Tag[]
     */
    private function parseTagBlock($tags, Types\Context $context)
    {
        $tags = $this->filterTagBlock($tags);
        if (!$tags) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

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

        $result = $this->splitTagBlockIntoTagLines($tags);
        foreach ($result as $key => $tagLine) {
            $result[$key] = $this->tagFactory->create(trim($tagLine), $context);
        }

        return $result;
class Author {
    private $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function getName() {
        return $this->name;
    }
}

abstract class Post {
    public function getAuthor() {
        return new Author('Johannes');
    }
}

class BlogPost extends Post {
    public function getAuthor() {
        return 'Johannes';
    }
}

class ForumPost extends Post { /* ... */ }

function my_function(Post $post) {
    echo strtoupper($post->getAuthor());
}
    }

    /**
     * @param string $tags
     *
     * @return string[]
     */
    private function splitTagBlockIntoTagLines($tags)
    {
        $result = array();
        foreach (explode("\n", $tags) as $tag_line) {
            if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
                $result[] = $tag_line;
            } else {
                $result[count($result) - 1] .= "\n" . $tag_line;
            }
        }

        return $result;
    }

    /**
     * @param $tags
     * @return string
     */
    private function filterTagBlock($tags)
    {
        $tags = trim($tags);
        if (!$tags) {
            return null;
        }

        if ('@' !== $tags[0]) {
            // @codeCoverageIgnoreStart
            // Can't simulate this; this only happens if there is an error with the parsing of the DocBlock that
            // we didn't foresee.
            throw new \LogicException('A tag block started with text instead of an at-sign(@): ' . $tags);
            // @codeCoverageIgnoreEnd
        }

        return $tags;
    }
}


1		<?php
2		/**
3		* This file is part of phpDocumentor.
4		*
5		* For the full copyright and license information, please view the LICENSE
6		* file that was distributed with this source code.
7		*
8		* @copyright 2010-2015 Mike van Riel<[email protected]>
9		* @license http://www.opensource.org/licenses/mit-license.php MIT
10		* @link http://phpdoc.org
11		*/
12
13		namespace phpDocumentor\Reflection;
14
15		use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
16		use phpDocumentor\Reflection\DocBlock\StandardTagFactory;
17		use phpDocumentor\Reflection\DocBlock\Tag;
18		use phpDocumentor\Reflection\DocBlock\TagFactory;
19		use Webmozart\Assert\Assert;
20
21		final class DocBlockFactory implements DocBlockFactoryInterface
		0 ignored issues – show Complexity introduced 2016-02-26 16:20 UTC by Report Bug Copy Issue Report The class DocBlockFactory has a coupling between objects value of 16. Consider to reduce the number of dependencies under 13. Loading history...
22		{
23		/** @var DocBlock\DescriptionFactory */
24		private $descriptionFactory;
25
26		/** @var DocBlock\TagFactory */
27		private $tagFactory;
28
29		/**
30		* Initializes this factory with the required subcontractors.
31		*
32		* @param DescriptionFactory $descriptionFactory
33		* @param TagFactory $tagFactory
34		*/
35	14	public function __construct(DescriptionFactory $descriptionFactory, TagFactory $tagFactory)
36		{
37	14	$this->descriptionFactory = $descriptionFactory;
38	14	$this->tagFactory = $tagFactory;
39	14	}
40
41		/**
42		* Factory method for easy instantiation.
43		*
44		* @param string[] $additionalTags
45		*
46		* @return DocBlockFactory
47		*/
48	1	public static function createInstance(array $additionalTags = [])
49		{
50	1	$fqsenResolver = new FqsenResolver();
51	1	$tagFactory = new StandardTagFactory($fqsenResolver);
52	1	$descriptionFactory = new DescriptionFactory($tagFactory);
53
54	1	$tagFactory->addService($descriptionFactory);
55	1	$tagFactory->addService(new TypeResolver($fqsenResolver));
56
57	1	$docBlockFactory = new self($descriptionFactory, $tagFactory);
58	1	foreach ($additionalTags as $tagName => $tagHandler) {
59		$docBlockFactory->registerTagHandler($tagName, $tagHandler);
60	1	}
61
62	1	return $docBlockFactory;
63		}
64
65		/**
66		* @param object\|string $docblock A string containing the DocBlock to parse or an object supporting the
67		* getDocComment method (such as a ReflectionClass object).
68		* @param Types\Context $context
69		* @param Location $location
70		*
71		* @return DocBlock
72		*/
73	13	public function create($docblock, Types\Context $context = null, Location $location = null)
74		{
75	13	if (is_object($docblock)) {
76	1	if (!method_exists($docblock, 'getDocComment')) {
77		$exceptionMessage = 'Invalid object passed; the given object must support the getDocComment method';
78		throw new \InvalidArgumentException($exceptionMessage);
79		}
80
81	1	$docblock = $docblock->getDocComment();
82	1	}
83
84	13	Assert::stringNotEmpty($docblock);
85
86	13	if ($context === null) {
87	10	$context = new Types\Context('');
88	10	}
89
90	13	$parts = $this->splitDocBlock($this->stripDocComment($docblock));
91	13	list($templateMarker, $summary, $description, $tags) = $parts;
92
93	13	return new DocBlock(
94	13	$summary,
95	13	$description ? $this->descriptionFactory->create($description, $context) : null,
96	13	array_filter($this->parseTagBlock($tags, $context), function($tag) {
		0 ignored issues – show Coding Style introduced 2016-02-26 20:55 UTC by Report Bug Copy Issue Report Expected 1 space after FUNCTION keyword; 0 found Loading history...
97	3	return $tag instanceof Tag;
98	13	}),
99	13	$context,
100	13	$location,
101	13	$templateMarker === '#@+',
102		$templateMarker === '#@-'
103	13	);
104		}
105
106		public function registerTagHandler($tagName, $handler)
107		{
108		$this->tagFactory->registerTagHandler($tagName, $handler);
109		}
110
111		/**
112		* Strips the asterisks from the DocBlock comment.
113		*
114		* @param string $comment String containing the comment text.
115		*
116		* @return string
117		*/
118	13	private function stripDocComment($comment)
119		{
120	13	$comment = trim(preg_replace('#[ \t](?:\/\\\|\\/\|\)?[ \t]{0,1}(.)?#u', '$1', $comment));
121
122		// reg ex above is not able to remove */ from a single line docblock
123	13	if (substr($comment, -2) == '*/') {
124	3	$comment = trim(substr($comment, 0, -2));
125	3	}
126
127	13	return str_replace(array("\r\n", "\r"), "\n", $comment);
128		}
129
130		/**
131		* Splits the DocBlock into a template marker, summary, description and block of tags.
132		*
133		* @param string $comment Comment to split into the sub-parts.
134		*
135		* @author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.
136		* @author Mike van Riel <[email protected]> for extending the regex with template marker support.
137		*
138		* @return string[] containing the template marker (if any), summary, description and a string containing the tags.
139		*/
140	13	private function splitDocBlock($comment)
141		{
142		// Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
143		// method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
144		// performance impact of running a regular expression
145	13	if (strpos($comment, '@') === 0) {
146	1	return array('', '', '', $comment);
147		}
148
149		// clears all extra horizontal whitespace from the line endings to prevent parsing issues
150	12	$comment = preg_replace('/\h*$/Sum', '', $comment);
151
152		/*
153		* Splits the docblock into a template marker, summary, description and tags section.
154		*
155		* - The template marker is empty, #@+ or #@- if the DocBlock starts with either of those (a newline may
156		* occur after it and will be stripped).
157		* - The short description is started from the first character until a dot is encountered followed by a
158		* newline OR two consecutive newlines (horizontal whitespace is taken into account to consider spacing
159		* errors). This is optional.
160		* - The long description, any character until a new line is encountered followed by an @ and word
161		* characters (a tag). This is optional.
162		* - Tags; the remaining characters
163		*
164		* Big thanks to RichardJ for contributing this Regular Expression
165		*/
166	12	preg_match(
167		'/
168		\A
169		# 1. Extract the template marker
170		(?:(\#\@\+\|\#\@\-)\n?)?
171
172		# 2. Extract the summary
173		(?:
174		(?! @\pL ) # The summary may not start with an @
175		(
176		[^\n.]+
177		(?:
178		(?! \. \n \| \n{2} ) # End summary upon a dot followed by newline or two newlines
179		[\n.] (?! [ \t]* @\pL ) # End summary when an @ is found as first character on a new line
180		[^\n.]+ # Include anything else
181		)*
182		\.?
183		)?
184		)
185
186		# 3. Extract the description
187		(?:
188		\s* # Some form of whitespace _must_ precede a description because a summary must be there
189		(?! @\pL ) # The description may not start with an @
190		(
191		[^\n]+
192		(?: \n+
193		(?! [ \t]* @\pL ) # End description when an @ is found as first character on a new line
194		[^\n]+ # Include anything else
195		)*
196		)
197		)?
198
199		# 4. Extract the tags (anything that follows)
200		(\s+ [\s\S]*)? # everything that follows
201	12	/ux',
202	12	$comment,
203		$matches
204	12	);
205	12	array_shift($matches);
206
207	12	while (count($matches) < 4) {
208	10	$matches[] = '';
209	10	}
210
211	12	return $matches;
212		}
213
214		/**
215		* Creates the tag objects.
216		*
217		* @param string $tags Tag block to parse.
218		* @param Types\Context $context Context of the parsed Tag
219		*
220		* @return DocBlock\Tag[]
221		*/
222	13	private function parseTagBlock($tags, Types\Context $context)
223		{
224	13	$tags = $this->filterTagBlock($tags);
225	13	if (!$tags) {
		0 ignored issues – show Bug Best Practice introduced 2015-12-22 13:00 UTC by Report Bug Copy Issue Report The expression `$tags` of type `null\|string` is loosely compared to `false`; 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...
226	10	return [];
227		}
228
229	3	$result = $this->splitTagBlockIntoTagLines($tags);
230	3	foreach ($result as $key => $tagLine) {
231	3	$result[$key] = $this->tagFactory->create(trim($tagLine), $context);
232	3	}
233
234	3	return $result;
		0 ignored issues – show Best Practice introduced 2015-12-22 13:00 UTC by Report Bug Copy Issue Report The expression `return $result;` seems to be an `array`, but some of its elements' types (`string`) are incompatible with the return type documented by `phpDocumentor\Reflection...kFactory::parseTagBlock` of type `phpDocumentor\Reflection\DocBlock\Tag[]`. If you return a value from a function or method, it should be a sub-type of the type that is given by the parent type f.e. an interface, or abstract method. This is more formally defined by the Lizkov substitution principle, and guarantees that classes that depend on the parent type can use any instance of a child type interchangably. This principle also belongs to the SOLID principles for object oriented design. Let’s take a look at an example: class Author { private $name; public function __construct($name) { $this->name = $name; } public function getName() { return $this->name; } } abstract class Post { public function getAuthor() { return new Author('Johannes'); } } class BlogPost extends Post { public function getAuthor() { return 'Johannes'; } } class ForumPost extends Post { /* ... */ } function my_function(Post $post) { echo strtoupper($post->getAuthor()); } Our function `my_function` expects a `Post` object, and outputs the author of the post. The base class `Post` returns a simple string and outputting a simple string will work just fine. However, the child class `BlogPost` which is a sub-type of `Post` instead decided to return an `object`, and is therefore violating the SOLID principles. If a `BlogPost` were passed to `my_function`, PHP would not complain, but ultimately fail when executing the `strtoupper` call in its body. Loading history...
235		}
236
237		/**
238		* @param string $tags
239		*
240		* @return string[]
241		*/
242	3	private function splitTagBlockIntoTagLines($tags)
243		{
244	3	$result = array();
245	3	foreach (explode("\n", $tags) as $tag_line) {
246	3	if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
247	3	$result[] = $tag_line;
248	3	} else {
249	2	$result[count($result) - 1] .= "\n" . $tag_line;
250		}
251	3	}
252
253	3	return $result;
254		}
255
256		/**
257		* @param $tags
258		* @return string
259		*/
260	13	private function filterTagBlock($tags)
261		{
262	13	$tags = trim($tags);
263	13	if (!$tags) {
264	10	return null;
265		}
266
267	3	if ('@' !== $tags[0]) {
268		// @codeCoverageIgnoreStart
269		// Can't simulate this; this only happens if there is an error with the parsing of the DocBlock that
270		// we didn't foresee.
271		throw new \LogicException('A tag block started with text instead of an at-sign(@): ' . $tags);
272		// @codeCoverageIgnoreEnd
273		}
274
275	3	return $tags;
276		}
277		}
278

phpDocumentor / ReflectionDocBlock

Pull Request — master (#102)

DocBlockFactory::create() B

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like