ParamTagSniff::loadArgumentTokenOfTag() - Code Metrics - Inspection of "Merge pull request #55 from bestit/bugfix/PHPCS-14..." - bestit/PHP_CodeSniffer - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — master ( e2e2f1...f855fb )

by Björn

created 2018-10-11 07:04 UTC

ParamTagSniff::loadArgumentTokenOfTag() A

↳ Parent: ParamTagSniff

Complexity

Conditions	1
Paths	1

Size

Total Lines

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
dl	0
loc	16
rs	9.7333
c	0
b	0
f	0
cc	1
nc	1
nop	0

<?php

declare(strict_types=1);

namespace BestIt\Sniffs\DocTags;

use BestIt\CodeSniffer\CodeError;
use BestIt\CodeSniffer\CodeWarning;
use SlevomatCodingStandard\Helpers\TokenHelper;
use function array_filter;
use function array_values;
use function in_array;
use function preg_quote;
use function strtolower;
use const T_CLOSE_PARENTHESIS;
use const T_DOC_COMMENT_OPEN_TAG;
use const T_VARIABLE;

/**
 * Sniff for the param tag content.
 *
 * @author blange <[email protected]>
 * @package BestIt\Sniffs\DocTags
 */
class ParamTagSniff extends AbstractTagSniff
{
    use TagContentFormatTrait;

    /**
     * The error code for the missing description.
     *
     * @var string
     */
    public const CODE_TAG_MISSING_DESC = 'MissingDesc';

    /**
     * The error code if the type of the param tag is missing.
     *
     * @var string
     */
    public const CODE_TAG_MISSING_TYPE = 'MissingType';

    /**
     * The error code if the matching property is missing.
     *
     * @var string
     */
    public const CODE_TAG_MISSING_VARIABLE = 'MissingVariable';

    /**
     * The error code if every property is missing.
     *
     * @var string
     */
    public const CODE_TAG_MISSING_VARIABLES = 'MissingVariables';

    /**
     * Error code for the mixed type.
     *
     * @var string
     */
    public const CODE_TAG_MIXED_TYPE = 'MixedType';

    /**
     * Message for displaying the missing description.
     *
     * @var string
     */
    private const MESSAGE_TAG_MISSING_DESC = 'There is no description for your tag: %s.';

    /**
     * Message for displaying the missing type.
     *
     * @var string
     */
    private const MESSAGE_TAG_MISSING_TYPE = 'There is no type for your tag: %s.';

    /**
     * Message for displaying the missing property.
     *
     * @var string
     */
    private const MESSAGE_TAG_MISSING_VARIABLE = 'There is no property for your tag "%s".';

    /**
     * Message for displaying the missing properties.
     *
     * @var string
     */
    private const MESSAGE_TAG_MISSING_VARIABLES = 'There are no properties for your tags.';

    /**
     * The message for the mixed type warning.
     *
     * @var string
     */
    private const MESSAGE_TAG_MIXED_TYPE = 'We suggest that you avoid the "mixed" type and declare the ' .
        'required types in detail.';

    /**
     * The token of the real function argument if it exists or null.
     *
     * @var array|null Is filled by runtime.
     */
    private $argumentToken = null;

    /**
     * The used variable tokens for this method.
     *
     * @var array
     */
    protected $varTokens;

    /**
     * Simple check if the pattern is correct.
     *
     * @param string|null $tagContent
     * @throws CodeWarning
     *
     * @return bool True if it matches.
     */
    private function checkAgainstPattern(?string $tagContent = null): bool
    {
        if (!$return = $this->isValidContent($tagContent)) {
            throw (new CodeError(self::CODE_TAG_MISSING_VARIABLE, self::MESSAGE_TAG_MISSING_VARIABLE, $this->stackPos))
                ->setPayload([$tagContent])
                ->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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

        return $return;
    }

    /**
     * Checks if the argument of the function itself exists.
     *
     * @param null|string $tagContent
     * @throws CodeWarning
     *
     * @return void
     */
    private function checkArgumentItself(?string $tagContent = null): void
    {
        if (!$this->getArgumentTokenOfTag()) {
            throw (new CodeError(
                static::CODE_TAG_MISSING_VARIABLE,
                self::MESSAGE_TAG_MISSING_VARIABLE,
                $this->stackPos
            ))
                ->setPayload([$tagContent])
                ->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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

    /**
     * Checks if the param contains a description.
     *
     * @throws CodeWarning
     *
     * @return bool Returns true if there is a desc.
     */
    private function checkDescription(): bool
    {
        if ($hasNoDesc = !@$this->matches['desc']) {
            throw (new CodeWarning(self::CODE_TAG_MISSING_DESC, self::MESSAGE_TAG_MISSING_DESC, $this->stackPos))
                ->setPayload([$this->matches['var']])
                ->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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

        return !$hasNoDesc;
    }

    /**
     * Checks if the param tag contains a valid type.
     *
     * @throws CodeWarning
     *
     * @return bool True if the type is valid.
     */
    private function checkType(): bool
    {
        if (!@$this->matches['type']) {
            throw (new CodeError(self::CODE_TAG_MISSING_TYPE, self::MESSAGE_TAG_MISSING_TYPE, $this->stackPos))
                ->setPayload([$this->matches['var']])
                ->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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

        if (strtolower($this->matches['type']) === 'mixed') {
            throw (new CodeWarning(self::CODE_TAG_MIXED_TYPE, self::MESSAGE_TAG_MIXED_TYPE, $this->stackPos))
                ->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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


        return true;
    }

    /**
     * Loads all variables of the following method.
     *
     * @return array
     */
    protected function findAllVariablePositions(): array
    {
        return TokenHelper::findNextAll(
            $this->file->getBaseFile(),
            [T_VARIABLE],
            $this->stackPos + 1,
            $this->file->findNext([T_CLOSE_PARENTHESIS], $this->stackPos + 1)
        );
    }

    /**
     * Returns a pattern to check if the content is valid.
     *
     * @return string The pattern which matches successful.
     */
    protected function getValidPattern(): string
    {
        $varOfThisTag = $this->getArgumentTokenOfTag();

        return '/(?P<type>[\w|\|\[\]]*) ?(?P<var>' . preg_quote($varOfThisTag['content'], '/') .
            ') ?(?P<desc>.*)/m';
    }

    /**
     * Returns the name of the real function argument for this parameter tag.
     *
     * @return array Null if there is no matching function argument.
     */
    private function getArgumentTokenOfTag(): array
    {
        if ($this->argumentToken === null) {
            $this->argumentToken = $this->loadArgumentTokenOfTag();
        }

        return $this->argumentToken;
    }

    /**
     * Loads and checks the variables of the following method.
     *
     * @throws CodeWarning We have param tags, so there should be variables in the method.
     *
     * @return array The positions of the methods variables if there are any.
     */
    private function loadAndCheckVarPositions(): array
    {
        $varPositions = $this->findAllVariablePositions();

        if (!$varPositions) {

            throw (new CodeError(
                self::CODE_TAG_MISSING_VARIABLES,
                self::MESSAGE_TAG_MISSING_VARIABLES,
                $this->stackPos
            ))->setToken($this->token);
/**
 * @return array|string
 */
function returnsDifferentValues($x) {
    if ($x) {
        return 'foo';
    }

    return array();
}

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

        $this->varTokens = array_filter($this->tokens, function (array $token) use ($varPositions): bool {
            return in_array($token['pointer'], $varPositions, true);
        });

        return $varPositions;
    }

    /**
     * Loads the function argument of this tag.
     *
     * @return array
     */
    private function loadArgumentTokenOfTag(): array
    {
        // Give me the other tags of this doc block before this one.
        $tagPosBeforeThis = TokenHelper::findNextAll(
            $this->file->getBaseFile(),
            $this->register(),
            $this->file->findPrevious([T_DOC_COMMENT_OPEN_TAG], $this->stackPos),
            $this->stackPos - 1
        );

        $tagPosBeforeThis = array_filter($tagPosBeforeThis, function (int $position) {
            return $this->tokens[$position]['content'] === '@param';
        });

        return (array_values($this->varTokens)[count($tagPosBeforeThis)]) ?? [];
    }

    /**
     * Processed the content of the required tag.
     *
     * @param null|string $tagContent The possible tag content or null.
     * @throws CodeWarning
     *
     * @return void
     */
    protected function processTagContent(?string $tagContent = null): void
    {
        $varPoss = $this->loadAndCheckVarPositions();

        if ($varPoss) {

            $this->checkArgumentItself($tagContent);
            $this->checkAgainstPattern($tagContent);
            $this->checkType();
            $this->checkDescription();
        }
    }

    /**
     * For which tag should be sniffed?
     *
     * @return string The name of the tag without the "@"-prefix.
     */
    protected function registerTag(): string
    {
        return 'param';
    }

    /**
     * Sets up the test and loads the matching var if there is one.
     *
     * @return void
     */
    protected function setUp(): void
    {
        parent::setUp();

        $this->argumentToken = null;
    }
}


1			<?php
2
3			declare(strict_types=1);
4
5			namespace BestIt\Sniffs\DocTags;
6
7			use BestIt\CodeSniffer\CodeError;
8			use BestIt\CodeSniffer\CodeWarning;
9			use SlevomatCodingStandard\Helpers\TokenHelper;
10			use function array_filter;
11			use function array_values;
12			use function in_array;
13			use function preg_quote;
14			use function strtolower;
15			use const T_CLOSE_PARENTHESIS;
16			use const T_DOC_COMMENT_OPEN_TAG;
17			use const T_VARIABLE;
18
19			/**
20			* Sniff for the param tag content.
21			*
22			* @author blange <[email protected]>
23			* @package BestIt\Sniffs\DocTags
24			*/
25			class ParamTagSniff extends AbstractTagSniff
26			{
27			use TagContentFormatTrait;
28
29			/**
30			* The error code for the missing description.
31			*
32			* @var string
33			*/
34			public const CODE_TAG_MISSING_DESC = 'MissingDesc';
35
36			/**
37			* The error code if the type of the param tag is missing.
38			*
39			* @var string
40			*/
41			public const CODE_TAG_MISSING_TYPE = 'MissingType';
42
43			/**
44			* The error code if the matching property is missing.
45			*
46			* @var string
47			*/
48			public const CODE_TAG_MISSING_VARIABLE = 'MissingVariable';
49
50			/**
51			* The error code if every property is missing.
52			*
53			* @var string
54			*/
55			public const CODE_TAG_MISSING_VARIABLES = 'MissingVariables';
56
57			/**
58			* Error code for the mixed type.
59			*
60			* @var string
61			*/
62			public const CODE_TAG_MIXED_TYPE = 'MixedType';
63
64			/**
65			* Message for displaying the missing description.
66			*
67			* @var string
68			*/
69			private const MESSAGE_TAG_MISSING_DESC = 'There is no description for your tag: %s.';
70
71			/**
72			* Message for displaying the missing type.
73			*
74			* @var string
75			*/
76			private const MESSAGE_TAG_MISSING_TYPE = 'There is no type for your tag: %s.';
77
78			/**
79			* Message for displaying the missing property.
80			*
81			* @var string
82			*/
83			private const MESSAGE_TAG_MISSING_VARIABLE = 'There is no property for your tag "%s".';
84
85			/**
86			* Message for displaying the missing properties.
87			*
88			* @var string
89			*/
90			private const MESSAGE_TAG_MISSING_VARIABLES = 'There are no properties for your tags.';
91
92			/**
93			* The message for the mixed type warning.
94			*
95			* @var string
96			*/
97			private const MESSAGE_TAG_MIXED_TYPE = 'We suggest that you avoid the "mixed" type and declare the ' .
98			'required types in detail.';
99
100			/**
101			* The token of the real function argument if it exists or null.
102			*
103			* @var array\|null Is filled by runtime.
104			*/
105			private $argumentToken = null;
106
107			/**
108			* The used variable tokens for this method.
109			*
110			* @var array
111			*/
112			protected $varTokens;
113
114			/**
115			* Simple check if the pattern is correct.
116			*
117			* @param string\|null $tagContent
118			* @throws CodeWarning
119			*
120			* @return bool True if it matches.
121			*/
122			private function checkAgainstPattern(?string $tagContent = null): bool
123			{
124			if (!$return = $this->isValidContent($tagContent)) {
125			throw (new CodeError(self::CODE_TAG_MISSING_VARIABLE, self::MESSAGE_TAG_MISSING_VARIABLE, $this->stackPos))
126			->setPayload([$tagContent])
127			->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-09-21 08:44 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
128			}
129
130			return $return;
131			}
132
133			/**
134			* Checks if the argument of the function itself exists.
135			*
136			* @param null\|string $tagContent
137			* @throws CodeWarning
138			*
139			* @return void
140			*/
141			private function checkArgumentItself(?string $tagContent = null): void
142			{
143			if (!$this->getArgumentTokenOfTag()) {
144			throw (new CodeError(
145			static::CODE_TAG_MISSING_VARIABLE,
146			self::MESSAGE_TAG_MISSING_VARIABLE,
147			$this->stackPos
148			))
149			->setPayload([$tagContent])
150			->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-10-10 20:47 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
151			}
152			}
153
154			/**
155			* Checks if the param contains a description.
156			*
157			* @throws CodeWarning
158			*
159			* @return bool Returns true if there is a desc.
160			*/
161			private function checkDescription(): bool
162			{
163			if ($hasNoDesc = !@$this->matches['desc']) {
164			throw (new CodeWarning(self::CODE_TAG_MISSING_DESC, self::MESSAGE_TAG_MISSING_DESC, $this->stackPos))
165			->setPayload([$this->matches['var']])
166			->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-09-21 08:44 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
167			}
168
169			return !$hasNoDesc;
170			}
171
172			/**
173			* Checks if the param tag contains a valid type.
174			*
175			* @throws CodeWarning
176			*
177			* @return bool True if the type is valid.
178			*/
179			private function checkType(): bool
180			{
181			if (!@$this->matches['type']) {
182			throw (new CodeError(self::CODE_TAG_MISSING_TYPE, self::MESSAGE_TAG_MISSING_TYPE, $this->stackPos))
183			->setPayload([$this->matches['var']])
184			->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-10-03 09:51 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
185			}
186
187			if (strtolower($this->matches['type']) === 'mixed') {
188			throw (new CodeWarning(self::CODE_TAG_MIXED_TYPE, self::MESSAGE_TAG_MIXED_TYPE, $this->stackPos))
189			->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-10-03 09:51 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
190			}
191
192
193			return true;
194			}
195
196			/**
197			* Loads all variables of the following method.
198			*
199			* @return array
200			*/
201			protected function findAllVariablePositions(): array
202			{
203			return TokenHelper::findNextAll(
204			$this->file->getBaseFile(),
205			[T_VARIABLE],
206			$this->stackPos + 1,
207			$this->file->findNext([T_CLOSE_PARENTHESIS], $this->stackPos + 1)
208			);
209			}
210
211			/**
212			* Returns a pattern to check if the content is valid.
213			*
214			* @return string The pattern which matches successful.
215			*/
216			protected function getValidPattern(): string
217			{
218			$varOfThisTag = $this->getArgumentTokenOfTag();
219
220			return '/(?P<type>[\w\|\\|\[\]]*) ?(?P<var>' . preg_quote($varOfThisTag['content'], '/') .
221			') ?(?P<desc>.*)/m';
222			}
223
224			/**
225			* Returns the name of the real function argument for this parameter tag.
226			*
227			* @return array Null if there is no matching function argument.
228			*/
229			private function getArgumentTokenOfTag(): array
230			{
231			if ($this->argumentToken === null) {
232			$this->argumentToken = $this->loadArgumentTokenOfTag();
233			}
234
235			return $this->argumentToken;
236			}
237
238			/**
239			* Loads and checks the variables of the following method.
240			*
241			* @throws CodeWarning We have param tags, so there should be variables in the method.
242			*
243			* @return array The positions of the methods variables if there are any.
244			*/
245			private function loadAndCheckVarPositions(): array
246			{
247			$varPositions = $this->findAllVariablePositions();
248
249			if (!$varPositions) {
			0 ignored issues – show Bug Best Practice introduced 2018-10-10 20:47 UTC by Report Bug Copy Issue Report The expression `$varPositions` of type `array` is implicitly converted to a boolean; are you sure this is intended? If so, consider using `empty($expr)` instead to make it clear that you intend to check for an array without elements. This check marks implicit conversions of arrays to boolean values in a comparison. While in PHP an empty array is considered to be equal (but not identical) to false, this is not always apparent. Consider making the comparison explicit by using `empty(..)` or `! empty(...)` instead. Loading history...
250			throw (new CodeError(
251			self::CODE_TAG_MISSING_VARIABLES,
252			self::MESSAGE_TAG_MISSING_VARIABLES,
253			$this->stackPos
254			))->setToken($this->token);
			0 ignored issues – show Bug introduced 2018-10-10 20:47 UTC by Report Bug Copy Issue Report It seems like `$this->token` can also be of type `null`; however, `BestIt\CodeSniffer\CodeWarning::setToken()` does only seem to accept `array`, 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...
255			}
256
257			$this->varTokens = array_filter($this->tokens, function (array $token) use ($varPositions): bool {
258			return in_array($token['pointer'], $varPositions, true);
259			});
260
261			return $varPositions;
262			}
263
264			/**
265			* Loads the function argument of this tag.
266			*
267			* @return array
268			*/
269			private function loadArgumentTokenOfTag(): array
270			{
271			// Give me the other tags of this doc block before this one.
272			$tagPosBeforeThis = TokenHelper::findNextAll(
273			$this->file->getBaseFile(),
274			$this->register(),
275			$this->file->findPrevious([T_DOC_COMMENT_OPEN_TAG], $this->stackPos),
276			$this->stackPos - 1
277			);
278
279			$tagPosBeforeThis = array_filter($tagPosBeforeThis, function (int $position) {
280			return $this->tokens[$position]['content'] === '@param';
281			});
282
283			return (array_values($this->varTokens)[count($tagPosBeforeThis)]) ?? [];
284			}
285
286			/**
287			* Processed the content of the required tag.
288			*
289			* @param null\|string $tagContent The possible tag content or null.
290			* @throws CodeWarning
291			*
292			* @return void
293			*/
294			protected function processTagContent(?string $tagContent = null): void
295			{
296			$varPoss = $this->loadAndCheckVarPositions();
297
298			if ($varPoss) {
			0 ignored issues – show Bug Best Practice introduced 2018-09-21 08:44 UTC by Report Bug Copy Issue Report The expression `$varPoss` of type `array` is implicitly converted to a boolean; are you sure this is intended? If so, consider using `! empty($expr)` instead to make it clear that you intend to check for an array without elements. This check marks implicit conversions of arrays to boolean values in a comparison. While in PHP an empty array is considered to be equal (but not identical) to false, this is not always apparent. Consider making the comparison explicit by using `empty(..)` or `! empty(...)` instead. Loading history...
299			$this->checkArgumentItself($tagContent);
300			$this->checkAgainstPattern($tagContent);
301			$this->checkType();
302			$this->checkDescription();
303			}
304			}
305
306			/**
307			* For which tag should be sniffed?
308			*
309			* @return string The name of the tag without the "@"-prefix.
310			*/
311			protected function registerTag(): string
312			{
313			return 'param';
314			}
315
316			/**
317			* Sets up the test and loads the matching var if there is one.
318			*
319			* @return void
320			*/
321			protected function setUp(): void
322			{
323			parent::setUp();
324
325			$this->argumentToken = null;
326			}
327			}
328

bestit / PHP_CodeSniffer

Push — master ( e2e2f1...f855fb )

ParamTagSniff::loadArgumentTokenOfTag() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like