coding-standard/src/DocBlock/UselessDocBlockCleaner.php at b9ceeadf3740de8d67bd9a8f1a8c0cfe41c86d91 · symplify/coding-standard · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
<?php

declare(strict_types=1);

namespace Symplify\CodingStandard\DocBlock;

use Nette\Utils\Strings;
use PhpCsFixer\Tokenizer\Token;

final class UselessDocBlockCleaner
{
    /**
     * @var string[]
     */
    private const CLEANING_REGEXES = [
        self::TODO_COMMENT_BY_PHPSTORM_REGEX,
        self::TODO_IMPLEMENT_METHOD_COMMENT_BY_PHPSTORM_REGEX,
        self::COMMENT_CONSTRUCTOR_CLASS_REGEX,

        // must run first
        self::STANDALONE_DOCBLOCK_CLASS_REGEX,
        // then this one
        self::STANDALONE_COMMENT_CLASS_REGEX,
        // then this one
        self::INLINE_COMMENT_CLASS_REGEX,
    ];

    /**
     * @see https://regex101.com/r/5fQJkz/2
     * @var string
     */
    private const TODO_IMPLEMENT_METHOD_COMMENT_BY_PHPSTORM_REGEX = '#\/\/ TODO: Implement .*\(\) method.$#';

    /**
     * @see https://regex101.com/r/zayQpv/1
     * @var string
     */
    private const TODO_COMMENT_BY_PHPSTORM_REGEX = '#\/\/ TODO: Change the autogenerated stub$#';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const STANDALONE_DOCBLOCK_CLASS_REGEX = '#(\/\*\*\s+)\*\s+[cC]lass\s+[^\s]*(\s+\*\/)$#';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const STANDALONE_COMMENT_CLASS_REGEX = '#\/\/\s+(class|trait|interface)\s+\w+$#i';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const INLINE_COMMENT_CLASS_REGEX = '#\s\*\s(class|trait|interface)\s+(\w)+$#i';

    /**
     * @var string
     */
    private const COMMENT_CONSTRUCTOR_CLASS_REGEX = '#^(\/\/|(\s|\*)+)(\s\w+\s)?constructor(\.)?$#i';

    /**
     * @see https://regex101.com/r/1kcgR5/1
     * @var string
     */
    private const DOCTRINE_GENERATED_COMMENT_REGEX = '#^(\/\*{2}\s+?)?(\*|\/\/)\s+This class was generated by the Doctrine ORM\. Add your own custom\r?\n\s+\*\s+repository methods below\.(\s+\*\/)$#';

    public function clearDocTokenContent(Token $currentToken, ?string $classLikeName): string
    {
        $docContent = $currentToken->getContent();

        $cleanedCommentLines = [];

        foreach (explode("\n", $docContent) as $key => $commentLine) {
            if ($this->isClassLikeName($commentLine, $classLikeName)) {
                continue;
            }

            foreach (self::CLEANING_REGEXES as $cleaningRegex) {
                $commentLine = Strings::replace($commentLine, $cleaningRegex);
            }

            $cleanedCommentLines[$key] = $commentLine;
        }

        // remove empty lines
        $cleanedCommentLines = array_filter($cleanedCommentLines);
        $cleanedCommentLines = array_values($cleanedCommentLines);

        // is totally empty?
        if ($this->isEmptyDocblock($cleanedCommentLines)) {
            return '';
        }

        $commentText = implode("\n", $cleanedCommentLines);

        // run multilines regex on final result
        return Strings::replace($commentText, self::DOCTRINE_GENERATED_COMMENT_REGEX);
    }

    /**
     * @param string[] $commentLines
     */
    private function isEmptyDocblock(array $commentLines): bool
    {
        if (count($commentLines) !== 2) {
            return false;
        }

        $startCommentLine = $commentLines[0];
        $endCommentLine = $commentLines[1];

        return $startCommentLine === '/**' && trim($endCommentLine) === '*/';
    }

    private function isClassLikeName(string $commentLine, ?string $classLikeName): bool
    {
        if ($classLikeName === null) {
            return false;
        }

        return trim($commentLine, '* ') === $classLikeName;
    }
}