From 03b9b65585c3709781bbd52ebb2f228f567dcb85 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 12 Aug 2022 18:40:23 +0200
Subject: [PATCH] :sparkles: New `WordPress.WhiteSpace.ObjectOperatorSpacing`
 sniff

This sniff largely defers to the upstream `Squiz.WhiteSpace.ObjectOperatorSpacing` sniff, which was previously already included.

The only real difference between the two sniffs is that for class resolution using `ClassName::class`, new lines around the `::` object operator will not be ignored.

The WPCS sniff has the same default property settings as the upstream sniff and changes to the property values should be made in the ruleset.

Includes docs.
Includes unit tests covering the difference and safeguarding that the sniff doesn't overreach.
---
 WordPress-Core/ruleset.xml                    |  2 +-
 .../ObjectOperatorSpacingStandard.xml         | 19 ++++++
 .../WhiteSpace/ObjectOperatorSpacingSniff.php | 65 +++++++++++++++++++
 .../ObjectOperatorSpacingUnitTest.inc         | 55 ++++++++++++++++
 .../ObjectOperatorSpacingUnitTest.inc.fixed   | 45 +++++++++++++
 .../ObjectOperatorSpacingUnitTest.php         | 59 +++++++++++++++++
 6 files changed, 244 insertions(+), 1 deletion(-)
 create mode 100644 WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml
 create mode 100644 WordPress/Sniffs/WhiteSpace/ObjectOperatorSpacingSniff.php
 create mode 100644 WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc
 create mode 100644 WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc.fixed
 create mode 100644 WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.php

diff --git a/WordPress-Core/ruleset.xml b/WordPress-Core/ruleset.xml
index eee861589b..b467c8e930 100644
--- a/WordPress-Core/ruleset.xml
+++ b/WordPress-Core/ruleset.xml
@@ -526,7 +526,7 @@
 	<rule ref="Generic.Classes.OpeningBraceSameLine"/>
 
 	<!-- Object operators should not have whitespace around them unless they are multi-line. -->
-	<rule ref="Squiz.WhiteSpace.ObjectOperatorSpacing">
+	<rule ref="WordPress.WhiteSpace.ObjectOperatorSpacing">
 		<properties>
 			<property name="ignoreNewlines" value="true"/>
 		</properties>
diff --git a/WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml b/WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml
new file mode 100644
index 0000000000..47ffb1e8e6
--- /dev/null
+++ b/WordPress/Docs/WhiteSpace/ObjectOperatorSpacingStandard.xml
@@ -0,0 +1,19 @@
+<documentation title="Object Operator Spacing">
+    <standard>
+    <![CDATA[
+    The object operators (->, ?->, ::) should not have any spaces around them, though new lines are allowed except for use with the `::class` constant.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: No spaces around the object operator.">
+        <![CDATA[
+$foo<em></em>-><em></em>bar();
+        ]]>
+        </code>
+        <code title="Invalid: Whitespace surrounding the object operator.">
+        <![CDATA[
+$foo<em>  </em>?-><em>  </em>bar();
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>
diff --git a/WordPress/Sniffs/WhiteSpace/ObjectOperatorSpacingSniff.php b/WordPress/Sniffs/WhiteSpace/ObjectOperatorSpacingSniff.php
new file mode 100644
index 0000000000..2970fe927d
--- /dev/null
+++ b/WordPress/Sniffs/WhiteSpace/ObjectOperatorSpacingSniff.php
@@ -0,0 +1,65 @@
+<?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPressCS\WordPress\Sniffs\WhiteSpace;
+
+use PHP_CodeSniffer\Standards\Squiz\Sniffs\WhiteSpace\ObjectOperatorSpacingSniff as Squiz_ObjectOperatorSpacingSniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Ensure there is no whitespace before/after an object operator.
+ *
+ * Difference with the upstream sniff:
+ * - When the `::` operator is used in `::class`, no new line(s) before or after the object operator are allowed.
+ *
+ * @package WPCS\WordPressCodingStandards
+ *
+ * @since 3.0.0
+ * @link  https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Squiz/Sniffs/WhiteSpace/ObjectOperatorSpacingSniff.php
+ */
+class ObjectOperatorSpacingSniff extends Squiz_ObjectOperatorSpacingSniff {
+
+	/**
+	 * Processes this test, when one of its tokens is encountered.
+	 *
+	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+	 * @param int                         $stackPtr  The position of the current token
+	 *                                               in the stack passed in $tokens.
+	 *
+	 * @return void|int Optionally returns a stack pointer. The sniff will not be
+	 *                  called again on the current file until the returned stack
+	 *                  pointer is reached.
+	 */
+	public function process( File $phpcsFile, $stackPtr ) {
+		$tokens            = $phpcsFile->getTokens();
+		$property_adjusted = false;
+
+		// Check for `::class` and don't ignore new lines in that case.
+		if ( true === $this->ignoreNewlines
+			&& \T_DOUBLE_COLON === $tokens[ $stackPtr ]['code']
+		) {
+			$next_non_empty = $phpcsFile->findNext( Tokens::$emptyTokens, ( $stackPtr + 1 ), null, true );
+			if ( \T_STRING === $tokens[ $next_non_empty ]['code']
+				&& 'class' === strtolower( $tokens[ $next_non_empty ]['content'] )
+			) {
+				$property_adjusted    = true;
+				$this->ignoreNewlines = false;
+			}
+		}
+
+		$return = parent::process( $phpcsFile, $stackPtr );
+
+		if ( true === $property_adjusted ) {
+			$this->ignoreNewlines = true;
+		}
+
+		return $return;
+	}
+}
diff --git a/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc
new file mode 100644
index 0000000000..ec042a295f
--- /dev/null
+++ b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc
@@ -0,0 +1,55 @@
+<?php
+
+/*
+ * This test file only safeguards the bit where the sniff may behave differently from the upstream sniff.
+ */
+
+echo ObjectName::$prop;
+echo ObjectName::functionCall();
+echo ObjectName::class;
+
+echo ObjectName  ::   $prop; // Error x 2.
+echo ObjectName ::  functionCall(); // Error x 2.
+echo ObjectName   :: class; // Error x 2.
+
+echo ObjectName
+	::
+	$prop; // Error x 2.
+echo ObjectName
+	::
+	functionCall(); // Error x 2.
+echo ObjectName
+	::
+	class; // Error x 2.
+
+echo ObjectName // Comment
+	::
+	/* comment */
+	class; // Error x 2.
+
+// phpcs:set WordPress.WhiteSpace.ObjectOperatorSpacing ignoreNewlines true
+
+echo ObjectName::$prop;
+echo ObjectName::functionCall();
+echo ObjectName::class;
+
+echo ObjectName  ::   $prop; // Error x 2.
+echo ObjectName ::  functionCall(); // Error x 2.
+echo ObjectName   :: class; // Error x 2.
+
+echo ObjectName
+	::
+	$prop;
+echo ObjectName
+	::
+	functionCall();
+echo ObjectName
+	::
+	class; // Error x 2.
+
+echo ObjectName // Comment
+	::
+	/* comment */
+	class; // Error x 2.
+
+// phpcs:set WordPress.WhiteSpace.ObjectOperatorSpacing ignoreNewlines false
diff --git a/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc.fixed b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc.fixed
new file mode 100644
index 0000000000..5062a29cd3
--- /dev/null
+++ b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.inc.fixed
@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This test file only safeguards the bit where the sniff may behave differently from the upstream sniff.
+ */
+
+echo ObjectName::$prop;
+echo ObjectName::functionCall();
+echo ObjectName::class;
+
+echo ObjectName::$prop; // Error x 2.
+echo ObjectName::functionCall(); // Error x 2.
+echo ObjectName::class; // Error x 2.
+
+echo ObjectName::$prop; // Error x 2.
+echo ObjectName::functionCall(); // Error x 2.
+echo ObjectName::class; // Error x 2.
+
+echo ObjectName // Comment
+::/* comment */
+	class; // Error x 2.
+
+// phpcs:set WordPress.WhiteSpace.ObjectOperatorSpacing ignoreNewlines true
+
+echo ObjectName::$prop;
+echo ObjectName::functionCall();
+echo ObjectName::class;
+
+echo ObjectName::$prop; // Error x 2.
+echo ObjectName::functionCall(); // Error x 2.
+echo ObjectName::class; // Error x 2.
+
+echo ObjectName
+	::
+	$prop;
+echo ObjectName
+	::
+	functionCall();
+echo ObjectName::class; // Error x 2.
+
+echo ObjectName // Comment
+::/* comment */
+	class; // Error x 2.
+
+// phpcs:set WordPress.WhiteSpace.ObjectOperatorSpacing ignoreNewlines false
diff --git a/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.php b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.php
new file mode 100644
index 0000000000..4ee31b2649
--- /dev/null
+++ b/WordPress/Tests/WhiteSpace/ObjectOperatorSpacingUnitTest.php
@@ -0,0 +1,59 @@
+<?php
+/**
+ * Unit test class for WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPressCS\WordPress\Tests\WhiteSpace;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the ObjectOperatorSpacing sniff.
+ *
+ * @package WPCS\WordPressCodingStandards
+ *
+ * @since 3.0.0
+ */
+class ObjectOperatorSpacingUnitTest extends AbstractSniffUnitTest {
+
+	/**
+	 * Returns the lines where errors should occur.
+	 *
+	 * The key of the array should represent the line number and the value
+	 * should represent the number of errors that should occur on that line.
+	 *
+	 * @return array<int, int>
+	 */
+	public function getErrorList() {
+		return array(
+			11 => 2,
+			12 => 2,
+			13 => 2,
+			16 => 2,
+			19 => 2,
+			22 => 2,
+			26 => 2,
+			36 => 2,
+			37 => 2,
+			38 => 2,
+			47 => 2,
+			51 => 2,
+		);
+	}
+
+	/**
+	 * Returns the lines where warnings should occur.
+	 *
+	 * The key of the array should represent the line number and the value
+	 * should represent the number of warnings that should occur on that line.
+	 *
+	 * @return array<int, int>
+	 */
+	public function getWarningList() {
+		return array();
+	}
+}