Squiz/EmbeddedPhp: bug fix - content intended indent calculation

The intended content indent calculation contained a pretty nasty bug, though it is unlikely to have been hit much in real code bases.

What was happening:
* The sniff would try to find the first whitespace token on the line containing the stack pointer.
    If found, the size of the whitespace was taken as the required indent. This part was working correctly.
* If no whitespace token was found, the sniff would try and find the first inline HTML token.
    If an inline HTML token was found, the leading whitespace in the inline HTML token was taken as the indent. This, again, is correct.
* However, now it gets iffy... what if no whitespace or inline HTML token was found on the line containing the open tag ? I.e. the situation where the open tag _is_ the first token on the line.
    This situation was not accounted for by the sniff.
    The `File::findFirstOnLine()` method would return `false` in that case, which means that the indent calculation would end up like this:
    ```php
    $indent = (strlen($tokens[false]['content']) - strlen(ltrim($tokens[false]['content'])));
    ```
    Now, `false` is not a valid array key, so this would end up being juggled to `0`, meaning the length of the leading whitespace for the first token in the **file** was being used.

Fixed now.

Includes various additional unit tests safeguarding the fix and one (in a separate file) demonstrating the situation where the bug would have had a real life impact.

Author: jrfnl

src/Standards/Squiz/Sniffs/PHP/EmbeddedPhpSniff.php

@@ -147,10 +147,13 @@ private function validateMultilineEmbeddedPhp($phpcsFile, $stackPtr, $closingTag
                     }
                 }//end if
 
-                $first = $phpcsFile->findFirstOnLine(T_WHITESPACE, $stackPtr);
+                $indent = 0;
+                $first  = $phpcsFile->findFirstOnLine(T_WHITESPACE, $stackPtr);
                 if ($first === false) {
-                    $first  = $phpcsFile->findFirstOnLine(T_INLINE_HTML, $stackPtr);
-                    $indent = (strlen($tokens[$first]['content']) - strlen(ltrim($tokens[$first]['content'])));
+                    $first = $phpcsFile->findFirstOnLine(T_INLINE_HTML, $stackPtr);
+                    if ($first !== false) {
+                        $indent = (strlen($tokens[$first]['content']) - strlen(ltrim($tokens[$first]['content'])));
+                    }
                 } else {
                     $indent = ($tokens[($first + 1)]['column'] - 1);
                 }

src/Standards/Squiz/Tests/PHP/EmbeddedPhpUnitTest.1.inc

@@ -199,6 +199,35 @@ Safeguard that blank lines between a PHP tag and a scope closer are not touched
 }
     ?>
 
+<!--
+Safeguard correct content indent calculation.
+-->
+<?php
+echo 'indent is correct - first on line for open tag is open tag';
+?>
+
+    <?php
+    echo 'indent is correct - first on line for open tag is inline HTML without content';
+    ?>
+        <div><?php
+        echo 'indent is correct - first on line for open tag is inline HTML with content';
+    ?><?php
+    echo 'indent is correct - first on line for open tag is whitespace';
+?>
+
+<?php
+    echo 'indent is incorrect - first on line for open tag is open tag';
+?>
+
+    <?php
+       echo 'indent is incorrect - first on line for open tag is inline HTML';
+    ?>
+        <div><?php
+                       echo 'indent is correct - first on line for open tag is inline HTML with content';
+    ?><?php
+echo 'indent is incorrect - first on line for open tag is whitespace';
+?>
+
 <?php
 // This test case file MUST always end with an unclosed long open PHP tag (with this comment) to prevent
 // the tests running into the "last PHP closing tag excepted" condition breaking tests.

src/Standards/Squiz/Tests/PHP/EmbeddedPhpUnitTest.1.inc.fixed

@@ -201,6 +201,39 @@ Safeguard that blank lines between a PHP tag and a scope closer are not touched
 }
     ?>
 
+<!--
+Safeguard correct content indent calculation.
+-->
+<?php
+echo 'indent is correct - first on line for open tag is open tag';
+?>
+
+    <?php
+    echo 'indent is correct - first on line for open tag is inline HTML without content';
+    ?>
+        <div>
+        <?php
+        echo 'indent is correct - first on line for open tag is inline HTML with content';
+    ?>
+    <?php
+    echo 'indent is correct - first on line for open tag is whitespace';
+?>
+
+<?php
+echo 'indent is incorrect - first on line for open tag is open tag';
+?>
+
+    <?php
+    echo 'indent is incorrect - first on line for open tag is inline HTML';
+    ?>
+        <div>
+        <?php
+        echo 'indent is correct - first on line for open tag is inline HTML with content';
+    ?>
+    <?php
+    echo 'indent is incorrect - first on line for open tag is whitespace';
+?>
+
 <?php
 // This test case file MUST always end with an unclosed long open PHP tag (with this comment) to prevent
 // the tests running into the "last PHP closing tag excepted" condition breaking tests.

src/Standards/Squiz/Tests/PHP/EmbeddedPhpUnitTest.22.inc

@@ -0,0 +1,20 @@
+                                <div>Inline HTML with indent to demonstrate the bug in the indent calculation.</div>
+<?php
+// This test case file MUST always start with a long open PHP tag set (with this comment) to prevent
+// the tests running into the "first PHP open tag excepted" condition breaking the tests.
+// Tests related to that "first PHP open tag excepted" condition should go in separate files.
+?>
+<!--
+Content indent calculation should not look at first token in the stack, but only at the line containing the PHP open tag for the block.
+-->
+<?php
+echo 'indent is correct - first on line for open tag is open tag';
+?>
+<?php
+       echo 'indent is incorrect - first on line for open tag is inline HTML';
+?>
+
+<?php
+// This test case file MUST always end with an unclosed long open PHP tag (with this comment) to prevent
+// the tests running into the "last PHP closing tag excepted" condition breaking tests.
+// Tests related to that "last PHP closing tag excepted" condition should go in separate files.

src/Standards/Squiz/Tests/PHP/EmbeddedPhpUnitTest.22.inc.fixed

@@ -0,0 +1,20 @@
+                                <div>Inline HTML with indent to demonstrate the bug in the indent calculation.</div>
+<?php
+// This test case file MUST always start with a long open PHP tag set (with this comment) to prevent
+// the tests running into the "first PHP open tag excepted" condition breaking the tests.
+// Tests related to that "first PHP open tag excepted" condition should go in separate files.
+?>
+<!--
+Content indent calculation should not look at first token in the stack, but only at the line containing the PHP open tag for the block.
+-->
+<?php
+echo 'indent is correct - first on line for open tag is open tag';
+?>
+<?php
+echo 'indent is incorrect - first on line for open tag is inline HTML';
+?>
+
+<?php
+// This test case file MUST always end with an unclosed long open PHP tag (with this comment) to prevent
+// the tests running into the "last PHP closing tag excepted" condition breaking tests.
+// Tests related to that "last PHP closing tag excepted" condition should go in separate files.

src/Standards/Squiz/Tests/PHP/EmbeddedPhpUnitTest.php

@@ -85,6 +85,14 @@ public function getErrorList($testFile='')
                 180 => 2,
                 181 => 1,
                 189 => 1,
+                212 => 1,
+                214 => 2,
+                219 => 1,
+                223 => 1,
+                225 => 1,
+                226 => 1,
+                227 => 2,
+                228 => 1,
             ];
 
         case 'EmbeddedPhpUnitTest.2.inc':
@@ -169,6 +177,9 @@ public function getErrorList($testFile='')
         case 'EmbeddedPhpUnitTest.21.inc':
             return [12 => 2];
 
+        case 'EmbeddedPhpUnitTest.22.inc':
+            return [14 => 1];
+
         default:
             return [];
         }//end switch