Security/EscapeOutput: improve handling of heredocs, include PHP 7.3+ flexible heredocs

As things were, when the sniff would encounter a heredoc, it would throw an error on the heredoc opener (`<<<EOD`) token and be done with it.

However, heredocs _can_, but don't necessarily always contain interpolated variables and expressions and when the heredoc doesn't contain any interpolation, it should be treated the same as any other plain text string.

This commit fixes the sniff to handle heredocs properly and throw errors only on heredoc lines containing interpolation.

Includes tests.

Author: jrfnl

WordPress/Sniffs/Security/EscapeOutputSniff.php

@@ -639,6 +639,25 @@ protected function check_code_is_escaped( $start, $end ) {
 				continue;
 			}
 
+			// Handle heredocs separately as they only need escaping when interpolation is used.
+			if ( \T_START_HEREDOC === $this->tokens[ $i ]['code'] ) {
+				$current = ( $i + 1 );
+				while ( isset( $this->tokens[ $current ] ) && \T_HEREDOC === $this->tokens[ $current ]['code'] ) {
+					$embeds = TextStrings::getEmbeds( $this->tokens[ $current ]['content'] );
+					if ( ! empty( $embeds ) ) {
+						$this->phpcsFile->addError(
+							'All output should be run through an escaping function (see the Security sections in the WordPress Developer Handbooks), found interpolation in unescaped heredoc.',
+							$current,
+							'HeredocOutputNotEscaped'
+						);
+					}
+					++$current;
+				}
+
+				$i = $current;
+				continue;
+			}
+
 			// Now check that next token is a function call.
 			if ( \T_STRING === $this->tokens[ $i ]['code'] ) {
 				$ptr                    = $i;

WordPress/Tests/Security/EscapeOutputUnitTest.1.inc

@@ -620,3 +620,24 @@ wp_die(
 		'exit'      => $do_exit, // Bad x 1.
 	)
 );
+
+// Heredocs should only be flagged when they contain interpolated variables or expressions.
+echo <<<EOD
+Some text without interpolation.
+EOD;
+
+echo <<<"EOD"
+Some text without interpolation.
+EOD;
+
+echo <<<EOD
+Some text $with interpolation.
+Some text $with interpolation.
+Some text $with interpolation.
+EOD;
+
+echo <<<"EOD"
+Some text without interpolation.
+Some text {$with->interpolation}.
+Some text without interpolation.
+EOD;

WordPress/Tests/Security/EscapeOutputUnitTest.20.inc

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * Tests with PHP 7.3+ flexible heredoc/nowdoc.
+ * This must be a separate test case file as it is a parse error in PHP < 7.3.
+ */
+
+// Heredocs should only be flagged when they contain interpolated variables or expressions.
+echo <<<EOD
+	Some text without interpolation.
+	EOD;
+
+echo <<<"EOD"
+    Some text without interpolation.
+    EOD;
+
+echo <<<EOD
+		Some text $with interpolation.
+		Some text $with interpolation.
+		Some text $with interpolation.
+	EOD; // Bad x 3.
+
+echo <<<"EOD"
+	Some text without interpolation.
+	Some text {$with->interpolation}.
+	Some text without interpolation.
+  EOD; // Bad.

WordPress/Tests/Security/EscapeOutputUnitTest.php

@@ -153,6 +153,10 @@ public function getErrorList( $testFile = '' ) {
 					617 => 1,
 					619 => 2,
 					620 => 1,
+					634 => 1,
+					635 => 1,
+					636 => 1,
+					641 => 1,
 				);
 
 			case 'EscapeOutputUnitTest.6.inc':
@@ -161,6 +165,19 @@ public function getErrorList( $testFile = '' ) {
 					4 => 1,
 				);
 
+			case 'EscapeOutputUnitTest.20.inc':
+				// These tests will only yield reliable results when PHPCS is run on PHP 7.3 or higher.
+				if ( \PHP_VERSION_ID < 70300 ) {
+					return array();
+				}
+
+				return array(
+					18 => 1,
+					19 => 1,
+					20 => 1,
+					25 => 1,
+				);
+
 			default:
 				return array();
 		}