From d960fd60da47c4c9f051797a069fef2c59a60f48 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 30 Oct 2022 01:29:25 +0200
Subject: [PATCH] :sparkles: New `Universal.Classes.ModifierKeywordOrder` sniff

Sniff to standardize the modifier keyword order for class declarations, what with the `readonly` keyword being introduced in PHP 8.2.

The sniff contains a `public` `$order` property which allows for configuring the preferred order.
Allowed values:
* `'extendability readonly'` (= default)
* `'readonly extendability'`

Includes fixer.
Includes unit tests.
Includes documentation.
Includes metrics.

Ref: https://wiki.php.net/rfc/readonly_classes
---
 .../Classes/ModifierKeywordOrderStandard.xml  |  27 +++
 .../Classes/ModifierKeywordOrderSniff.php     | 219 ++++++++++++++++++
 .../Classes/ModifierKeywordOrderUnitTest.inc  |  93 ++++++++
 .../ModifierKeywordOrderUnitTest.inc.fixed    |  90 +++++++
 .../Classes/ModifierKeywordOrderUnitTest.php  |  52 +++++
 5 files changed, 481 insertions(+)
 create mode 100644 Universal/Docs/Classes/ModifierKeywordOrderStandard.xml
 create mode 100644 Universal/Sniffs/Classes/ModifierKeywordOrderSniff.php
 create mode 100644 Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc
 create mode 100644 Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc.fixed
 create mode 100644 Universal/Tests/Classes/ModifierKeywordOrderUnitTest.php

diff --git a/Universal/Docs/Classes/ModifierKeywordOrderStandard.xml b/Universal/Docs/Classes/ModifierKeywordOrderStandard.xml
new file mode 100644
index 00000000..a80ae0da
--- /dev/null
+++ b/Universal/Docs/Classes/ModifierKeywordOrderStandard.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Class Modifier Keyword Order"
+    >
+    <standard>
+    <![CDATA[
+    Requires that class modifier keywords consistently use the same keyword order.
+
+    By default the expected order is "abstract/final readonly", but this can be changed via the sniff configuration.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Modifier keywords ordered correctly.">
+        <![CDATA[
+<em>final readonly</em> class Foo {}
+<em>abstract readonly</em> class Bar {}
+        ]]>
+        </code>
+        <code title="Invalid: Modifier keywords in reverse order.">
+        <![CDATA[
+<em>readonly final</em> class Foo {}
+<em>readonly abstract</em> class Bar {}
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>
diff --git a/Universal/Sniffs/Classes/ModifierKeywordOrderSniff.php b/Universal/Sniffs/Classes/ModifierKeywordOrderSniff.php
new file mode 100644
index 00000000..234515d8
--- /dev/null
+++ b/Universal/Sniffs/Classes/ModifierKeywordOrderSniff.php
@@ -0,0 +1,219 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2022 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Sniffs\Classes;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Tokens\Collections;
+
+/**
+ * Standardize the modifier keyword order for class declarations.
+ *
+ * @since 1.0.0-alpha4
+ */
+final class ModifierKeywordOrderSniff implements Sniff
+{
+
+    /**
+     * Name of the metric.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var string
+     */
+    const METRIC_NAME = 'Class modifier keyword order';
+
+    /**
+     * Order preference: abstract/final readonly.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var string
+     */
+    const EXTEND_READONLY = 'extendability readonly';
+
+    /**
+     * Order preference: readonly abstract/final.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var string
+     */
+    const READONLY_EXTEND = 'readonly extendability';
+
+    /**
+     * Preferred order for the modifier keywords.
+     *
+     * Accepted values:
+     * - "extendability readonly".
+     * - or "readonly extendability".
+     *
+     * Defaults to "extendability readonly".
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var string
+     */
+    public $order = self::EXTEND_READONLY;
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return [\T_CLASS];
+    }
+
+    /**
+     * Processes this test, when one of its tokens is encountered.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @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
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        /*
+         * Note to self: This can be switched to use the `ObjectDeclarations::getClassProperties()`
+         * method once that has been adjusted to return stackPtrs as well.
+         */
+        $tokens    = $phpcsFile->getTokens();
+        $valid     = Collections::classModifierKeywords() + Tokens::$emptyTokens;
+        $classProp = [
+            'abstract_token' => false,
+            'final_token'    => false,
+            'readonly_token' => false,
+        ];
+
+        for ($i = ($stackPtr - 1); $i > 0; $i--) {
+            if (isset($valid[$tokens[$i]['code']]) === false) {
+                break;
+            }
+
+            switch ($tokens[$i]['code']) {
+                case \T_ABSTRACT:
+                    $classProp['abstract_token'] = $i;
+                    break;
+
+                case \T_FINAL:
+                    $classProp['final_token'] = $i;
+                    break;
+
+                case \T_READONLY:
+                    $classProp['readonly_token'] = $i;
+                    break;
+            }
+        }
+
+        if ($classProp['readonly_token'] === false
+            || ($classProp['final_token'] === false && $classProp['abstract_token'] === false)
+        ) {
+            /*
+             * Either no modifier keywords found at all; or only one type of modifier
+             * keyword (abstract/final or readonly) declared, but not both. No ordering needed.
+             */
+            return;
+        }
+
+        if ($classProp['final_token'] !== false && $classProp['abstract_token'] !== false) {
+            // Parse error. Ignore.
+            return;
+        }
+
+        $readonly = $classProp['readonly_token'];
+
+        if ($classProp['final_token'] !== false) {
+            $extendability = $classProp['final_token'];
+        } else {
+            $extendability = $classProp['abstract_token'];
+        }
+
+        if ($readonly < $extendability) {
+            $phpcsFile->recordMetric($stackPtr, self::METRIC_NAME, self::READONLY_EXTEND);
+        } else {
+            $phpcsFile->recordMetric($stackPtr, self::METRIC_NAME, self::EXTEND_READONLY);
+        }
+
+        $message = 'Class modifier keywords are not in the correct order. Expected: "%s", found: "%s"';
+
+        switch ($this->order) {
+            case self::READONLY_EXTEND:
+                if ($readonly < $extendability) {
+                    // Order is correct. Nothing to do.
+                    return;
+                }
+
+                $this->handleError($phpcsFile, $extendability, $readonly);
+                break;
+
+            case self::EXTEND_READONLY:
+            default:
+                if ($extendability < $readonly) {
+                    // Order is correct. Nothing to do.
+                    return;
+                }
+
+                $this->handleError($phpcsFile, $readonly, $extendability);
+                break;
+        }
+    }
+
+    /**
+     * Throw the error and potentially fix it.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile     The file being scanned.
+     * @param int                         $firstKeyword  The position of the first keyword found.
+     * @param int                         $secondKeyword The position of the second keyword token.
+     *
+     * @return void
+     */
+    private function handleError(File $phpcsFile, $firstKeyword, $secondKeyword)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $message = 'Class modifier keywords are not in the correct order. Expected: "%s", found: "%s"';
+        $data    = [
+            $tokens[$secondKeyword]['content'] . ' ' . $tokens[$firstKeyword]['content'],
+            $tokens[$firstKeyword]['content'] . ' ' . $tokens[$secondKeyword]['content'],
+        ];
+
+        $fix = $phpcsFile->addFixableError($message, $firstKeyword, 'Incorrect', $data);
+
+        if ($fix === true) {
+            $phpcsFile->fixer->beginChangeset();
+
+            $phpcsFile->fixer->replaceToken($secondKeyword, '');
+
+            // Prevent leaving behind trailing whitespace.
+            $i = ($secondKeyword + 1);
+            while ($tokens[$i]['code'] === \T_WHITESPACE) {
+                $phpcsFile->fixer->replaceToken($i, '');
+                $i++;
+            }
+
+            // Use the original token content as the case used for keywords is not the concern of this sniff.
+            $phpcsFile->fixer->addContentBefore($firstKeyword, $tokens[$secondKeyword]['content'] . ' ');
+
+            $phpcsFile->fixer->endChangeset();
+        }
+    }
+}
diff --git a/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc
new file mode 100644
index 00000000..a78f9711
--- /dev/null
+++ b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc
@@ -0,0 +1,93 @@
+<?php
+
+/*
+ * Not our targets, no keyword possible.
+ * Includes some safeguarding against potential tokenizer issues.
+ */
+namespace Foo\class\bar;
+interface Foo {}
+$a = new class() {
+    public function class() {}
+};
+echo MyName::class;
+function_call(class: $var);
+
+/*
+ * OK, no or single keyword, no ordering needed.
+ */
+class NoModifiers {}
+
+final class OnlyFinal {}
+abstract class OnlyAbstract extends Something {}
+readonly class OnlyReadonly {}
+
+/*
+ * Ignore, compile errors, not our concern.
+ */
+final abstract class FinalAbstract {}
+
+readonly final abstract class ReadonlyFinalAbstract {}
+final readonly abstract class FinalReadonlyAbstract {}
+abstract readonly final class AbstractReadonlyFinal {}
+
+/*
+ * OK, expected order with default settings.
+ */
+#[SomeAttribute]
+final readonly class FinalReadonlyA {}
+
+abstract /*comment*/ readonly class AbstractReadonlyA implements MyInterface {}
+
+/*
+ * Bad with default settings.
+ */
+readonly final class ReadonlyFinalA {}
+
+ReadOnly Abstract class ReadonlyAbstractA extends Something {}
+
+readonly
+    // comment
+    final
+
+
+    // phpcs:ignore Stdn.Cat.SniffName -- for reasons.
+    class ReadonlyFinalB implements MyInterface {}
+
+readonly abstract /*comment*/ class ReadonlyAbstractB {}
+
+
+// phpcs:set Universal.Classes.ModifierKeywordOrder order readonly extendability
+
+/*
+ * OK, expected order with custom settings.
+ */
+readonly final class ReadonlyFinalC {}
+
+readonly abstract class ReadonlyAbstractC extends Something {}
+
+/*
+ * Bad with custom settings.
+ */
+FINAL readonly class FinalReadonlyB extends KeywordCaseShouldBeUnchanged {}
+
+abstract readonly class AbstractReadonlyB {}
+
+
+// phpcs:set Universal.Classes.ModifierKeywordOrder order readonly extends
+
+/*
+ * OK, expected order with invalid settings (default is used).
+ */
+abstract readonly class AbstractReadonlyC implements MyInterface {}
+
+/*
+ * Bad with invalid settings (default is used).
+ */
+readonly final class ReadonlyFinalD {}
+
+// Reset to default.
+// phpcs:set Universal.Classes.ModifierKeywordOrder order extendability readonly
+
+
+// Live coding. Ignore. This must be the last test in the file.
+class LiveCoding
diff --git a/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc.fixed b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc.fixed
new file mode 100644
index 00000000..d512b61a
--- /dev/null
+++ b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.inc.fixed
@@ -0,0 +1,90 @@
+<?php
+
+/*
+ * Not our targets, no keyword possible.
+ * Includes some safeguarding against potential tokenizer issues.
+ */
+namespace Foo\class\bar;
+interface Foo {}
+$a = new class() {
+    public function class() {}
+};
+echo MyName::class;
+function_call(class: $var);
+
+/*
+ * OK, no or single keyword, no ordering needed.
+ */
+class NoModifiers {}
+
+final class OnlyFinal {}
+abstract class OnlyAbstract extends Something {}
+readonly class OnlyReadonly {}
+
+/*
+ * Ignore, compile errors, not our concern.
+ */
+final abstract class FinalAbstract {}
+
+readonly final abstract class ReadonlyFinalAbstract {}
+final readonly abstract class FinalReadonlyAbstract {}
+abstract readonly final class AbstractReadonlyFinal {}
+
+/*
+ * OK, expected order with default settings.
+ */
+#[SomeAttribute]
+final readonly class FinalReadonlyA {}
+
+abstract /*comment*/ readonly class AbstractReadonlyA implements MyInterface {}
+
+/*
+ * Bad with default settings.
+ */
+final readonly class ReadonlyFinalA {}
+
+Abstract ReadOnly class ReadonlyAbstractA extends Something {}
+
+final readonly
+    // comment
+    // phpcs:ignore Stdn.Cat.SniffName -- for reasons.
+    class ReadonlyFinalB implements MyInterface {}
+
+abstract readonly /*comment*/ class ReadonlyAbstractB {}
+
+
+// phpcs:set Universal.Classes.ModifierKeywordOrder order readonly extendability
+
+/*
+ * OK, expected order with custom settings.
+ */
+readonly final class ReadonlyFinalC {}
+
+readonly abstract class ReadonlyAbstractC extends Something {}
+
+/*
+ * Bad with custom settings.
+ */
+readonly FINAL class FinalReadonlyB extends KeywordCaseShouldBeUnchanged {}
+
+readonly abstract class AbstractReadonlyB {}
+
+
+// phpcs:set Universal.Classes.ModifierKeywordOrder order readonly extends
+
+/*
+ * OK, expected order with invalid settings (default is used).
+ */
+abstract readonly class AbstractReadonlyC implements MyInterface {}
+
+/*
+ * Bad with invalid settings (default is used).
+ */
+final readonly class ReadonlyFinalD {}
+
+// Reset to default.
+// phpcs:set Universal.Classes.ModifierKeywordOrder order extendability readonly
+
+
+// Live coding. Ignore. This must be the last test in the file.
+class LiveCoding
diff --git a/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.php b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.php
new file mode 100644
index 00000000..78b9f509
--- /dev/null
+++ b/Universal/Tests/Classes/ModifierKeywordOrderUnitTest.php
@@ -0,0 +1,52 @@
+<?php
+/**
+ * PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
+ *
+ * @package   PHPCSExtra
+ * @copyright 2022 PHPCSExtra Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSExtra
+ */
+
+namespace PHPCSExtra\Universal\Tests\Classes;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the Classes\ModifierKeywordOrder sniff.
+ *
+ * @covers PHPCSExtra\Universal\Sniffs\Classes\ModifierKeywordOrderSniff
+ *
+ * @since 1.0.0
+ */
+final class ModifierKeywordOrderUnitTest extends AbstractSniffUnitTest
+{
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * @return array <int line number> => <int number of errors>
+     */
+    public function getErrorList()
+    {
+        return [
+            44 => 1,
+            46 => 1,
+            48 => 1,
+            56 => 1,
+            71 => 1,
+            73 => 1,
+            86 => 1,
+        ];
+    }
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * @return array <int line number> => <int number of warnings>
+     */
+    public function getWarningList()
+    {
+        return [];
+    }
+}