Skip to content

Commit 8a7ee56

Browse files
jrfnljrfnl
authored
✨ New Generic.Strings.UnnecessaryHeredoc sniff (#633)
New `Generic.Strings.UnnecessaryHeredoc` sniff which encourages the use of nowdocs instead of heredocs, when there is no interpolation or expressions in the body text. This sniff will hopefully help with the PERCS work as it intends to cover the following PER rule: > A nowdoc SHOULD be used wherever possible. Heredoc MAY be used when a nowdoc does not satisfy requirements. Includes fixer. Includes tests. Includes metrics. Includes XML docs.
1 parent 2fe2330 commit 8a7ee56

File tree

8 files changed

+648
-0
lines changed

8 files changed

+648
-0
lines changed

‎src/Standards/Generic/Docs/Strings/UnnecessaryHeredocStandard.xml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<documentation title="Unnecessary Heredoc">
2+
<standard>
3+
<![CDATA[
4+
If no interpolation or expressions are used in the body of a heredoc, nowdoc syntax should be used instead.
5+
]]>
6+
</standard>
7+
<code_comparison>
8+
<code title="Valid: Using nowdoc syntax for a text string without any interpolation or expressions.">
9+
<![CDATA[
10+
$nowdoc = <em><<<'EOD'</em>
11+
some text
12+
EOD;
13+
]]>
14+
</code>
15+
<code title="Invalid: Using heredoc syntax for a text string without any interpolation or expressions.">
16+
<![CDATA[
17+
$heredoc = <em><<<EOD</em>
18+
some text
19+
EOD;
20+
]]>
21+
</code>
22+
</code_comparison>
23+
<code_comparison>
24+
<code title="Valid: Using heredoc syntax for a text string containing interpolation or expressions.">
25+
<![CDATA[
26+
$heredoc = <em><<<"EOD"</em>
27+
some $text
28+
EOD;
29+
]]>
30+
</code>
31+
<code title="Invalid: Using heredoc syntax for a text string without any interpolation or expressions.">
32+
<![CDATA[
33+
$heredoc = <em><<<"EOD"</em>
34+
some text
35+
EOD;
36+
]]>
37+
</code>
38+
</code_comparison>
39+
</documentation>

‎src/Standards/Generic/Sniffs/Strings/UnnecessaryHeredocSniff.php‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
<?php
2+
/**
3+
* Prefer the use of nowdoc over heredoc.
4+
*
5+
* @author Juliette Reinders Folmer <[email protected]>
6+
* @copyright 2024 PHPCSStandards and contributors
7+
* @license https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
8+
*/
9+
10+
namespace PHP_CodeSniffer\Standards\Generic\Sniffs\Strings;
11+
12+
use PHP_CodeSniffer\Files\File;
13+
use PHP_CodeSniffer\Sniffs\Sniff;
14+
15+
class UnnecessaryHeredocSniff implements Sniff
16+
{
17+
18+
19+
/**
20+
* Returns an array of tokens this test wants to listen for.
21+
*
22+
* @return array<int|string>
23+
*/
24+
public function register()
25+
{
26+
return [T_START_HEREDOC];
27+
28+
}//end register()
29+
30+
31+
/**
32+
* Processes this test, when one of its tokens is encountered.
33+
*
34+
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
35+
* @param int $stackPtr The position of the current token in
36+
* the stack passed in $tokens.
37+
*
38+
* @return void
39+
*/
40+
public function process(File $phpcsFile, $stackPtr)
41+
{
42+
$tokens = $phpcsFile->getTokens();
43+
44+
if (isset($tokens[$stackPtr]['scope_closer']) === false) {
45+
// Just to be safe. Shouldn't be possible as in that case, the opener shouldn't be tokenized
46+
// to T_START_HEREDOC by PHP.
47+
return;
48+
}
49+
50+
$closer = $tokens[$stackPtr]['scope_closer'];
51+
$body = '';
52+
53+
// Collect all the tokens within the heredoc body.
54+
for ($i = ($stackPtr + 1); $i < $closer; $i++) {
55+
$body .= $tokens[$i]['content'];
56+
}
57+
58+
$tokenizedBody = token_get_all(sprintf("<?php <<<EOD\n%s\nEOD;\n?>", $body));
59+
foreach ($tokenizedBody as $ptr => $bodyToken) {
60+
if (is_array($bodyToken) === false) {
61+
continue;
62+
}
63+
64+
if ($bodyToken[0] === T_DOLLAR_OPEN_CURLY_BRACES
65+
|| $bodyToken[0] === T_VARIABLE
66+
) {
67+
// Contains interpolation or expression.
68+
$phpcsFile->recordMetric($stackPtr, 'Heredoc contains interpolation or expression', 'yes');
69+
return;
70+
}
71+
72+
if ($bodyToken[0] === T_CURLY_OPEN
73+
&& is_array($tokenizedBody[($ptr + 1)]) === false
74+
&& $tokenizedBody[($ptr + 1)] === '$'
75+
) {
76+
// Contains interpolation or expression.
77+
$phpcsFile->recordMetric($stackPtr, 'Heredoc contains interpolation or expression', 'yes');
78+
return;
79+
}
80+
}//end foreach
81+
82+
$phpcsFile->recordMetric($stackPtr, 'Heredoc contains interpolation or expression', 'no');
83+
84+
$warning = 'Detected heredoc without interpolation or expressions. Use nowdoc syntax instead';
85+
86+
$fix = $phpcsFile->addFixableWarning($warning, $stackPtr, 'Found');
87+
if ($fix === true) {
88+
$identifier = trim(ltrim($tokens[$stackPtr]['content'], '<'));
89+
$replaceWith = "'".trim($identifier, '"')."'";
90+
$replacement = str_replace($identifier, $replaceWith, $tokens[$stackPtr]['content']);
91+
$phpcsFile->fixer->replaceToken($stackPtr, $replacement);
92+
}
93+
94+
}//end process()
95+
96+
97+
}//end class

‎src/Standards/Generic/Tests/Strings/UnnecessaryHeredocUnitTest.1.inc‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<?php
2+
3+
/*
4+
* Test file 1 and 2 mirror each other, with file 1 containing non-indented cross-version compatible heredoc/nowdoc syntax,
5+
* while the code samples in file 2 use PHP 7.3+ flexible heredoc/nowdoc syntax.
6+
*
7+
* These two files should be kept in sync!
8+
*/
9+
10+
$nowdoc = <<<'EOD'
11+
some text
12+
EOD;
13+
14+
$heredoc = <<<END
15+
some $foo text
16+
END;
17+
18+
$heredoc = <<<"END"
19+
some {$foo[0]} text
20+
END;
21+
22+
$heredoc = <<<END
23+
{$foo?->bar}
24+
END;
25+
26+
$heredoc = <<< "END"
27+
some ${beers::softdrink}
28+
END;
29+
30+
$heredoc = <<< END
31+
{${$object->getName()}} text
32+
END;
33+
34+
$heredoc = <<<"END"
35+
some {${getName()}}
36+
END;
37+
38+
$heredoc = <<<END
39+
${substr('laruence', 0, 2)}
40+
END;
41+
42+
$heredoc = <<<"END"
43+
some {$foo['bar']->baz()()}
44+
END;
45+
46+
$heredoc = <<<END
47+
{$obj->values[3]->name} text
48+
END;
49+
50+
$heredoc = <<<"END"
51+
some ${$bar}
52+
END;
53+
54+
$heredoc = <<<END
55+
${foo->bar} text
56+
END;
57+
58+
$heredoc = <<<"END"
59+
${foo["${bar}"]} text
60+
END;
61+
62+
$heredoc = <<<END
63+
some ${foo["${bar[\'baz\']}"]}
64+
END;
65+
66+
$heredoc = <<<"END"
67+
${foo->{${'a'}}} text
68+
END;
69+
70+
$heredoc = <<<END
71+
some {$foo->{$baz[1]}}
72+
END;
73+
74+
$heredoc = <<<END
75+
some text
76+
{${beers::$ale}}
77+
some text
78+
END;
79+
80+
$heredoc = <<<"END"
81+
$people->john's wife greeted $people->robert.
82+
END;
83+
84+
$heredoc = <<<END
85+
Let's make sure it also works with this: {$arr[foo][3]}
86+
END;
87+
88+
$heredoc = <<<END
89+
Testing ${foo["${bar
90+
['baz']
91+
}"]} and more testing
92+
END;
93+
94+
$heredoc = <<<"END"
95+
Testing {${foo["${bar
96+
['baz']
97+
}"]}} and more testing
98+
END;
99+
100+
$heredoc = <<<END
101+
some text
102+
END;
103+
104+
$heredoc = <<< "END"
105+
some text
106+
some \$text
107+
some text
108+
END;

‎src/Standards/Generic/Tests/Strings/UnnecessaryHeredocUnitTest.1.inc.fixed‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<?php
2+
3+
/*
4+
* Test file 1 and 2 mirror each other, with file 1 containing non-indented cross-version compatible heredoc/nowdoc syntax,
5+
* while the code samples in file 2 use PHP 7.3+ flexible heredoc/nowdoc syntax.
6+
*
7+
* These two files should be kept in sync!
8+
*/
9+
10+
$nowdoc = <<<'EOD'
11+
some text
12+
EOD;
13+
14+
$heredoc = <<<END
15+
some $foo text
16+
END;
17+
18+
$heredoc = <<<"END"
19+
some {$foo[0]} text
20+
END;
21+
22+
$heredoc = <<<END
23+
{$foo?->bar}
24+
END;
25+
26+
$heredoc = <<< "END"
27+
some ${beers::softdrink}
28+
END;
29+
30+
$heredoc = <<< END
31+
{${$object->getName()}} text
32+
END;
33+
34+
$heredoc = <<<"END"
35+
some {${getName()}}
36+
END;
37+
38+
$heredoc = <<<END
39+
${substr('laruence', 0, 2)}
40+
END;
41+
42+
$heredoc = <<<"END"
43+
some {$foo['bar']->baz()()}
44+
END;
45+
46+
$heredoc = <<<END
47+
{$obj->values[3]->name} text
48+
END;
49+
50+
$heredoc = <<<"END"
51+
some ${$bar}
52+
END;
53+
54+
$heredoc = <<<END
55+
${foo->bar} text
56+
END;
57+
58+
$heredoc = <<<"END"
59+
${foo["${bar}"]} text
60+
END;
61+
62+
$heredoc = <<<END
63+
some ${foo["${bar[\'baz\']}"]}
64+
END;
65+
66+
$heredoc = <<<"END"
67+
${foo->{${'a'}}} text
68+
END;
69+
70+
$heredoc = <<<END
71+
some {$foo->{$baz[1]}}
72+
END;
73+
74+
$heredoc = <<<END
75+
some text
76+
{${beers::$ale}}
77+
some text
78+
END;
79+
80+
$heredoc = <<<"END"
81+
$people->john's wife greeted $people->robert.
82+
END;
83+
84+
$heredoc = <<<END
85+
Let's make sure it also works with this: {$arr[foo][3]}
86+
END;
87+
88+
$heredoc = <<<END
89+
Testing ${foo["${bar
90+
['baz']
91+
}"]} and more testing
92+
END;
93+
94+
$heredoc = <<<"END"
95+
Testing {${foo["${bar
96+
['baz']
97+
}"]}} and more testing
98+
END;
99+
100+
$heredoc = <<<'END'
101+
some text
102+
END;
103+
104+
$heredoc = <<< 'END'
105+
some text
106+
some \$text
107+
some text
108+
END;

0 commit comments

Comments
 (0)