Exception naming sniffs

.travis.yml

@@ -21,6 +21,8 @@ install: travis_retry composer update --prefer-dist
 script:
   - vendor/bin/phpcs
   - vendor/bin/phpcs $(find tests/input/* | sort) --report=summary --report-file=phpcs.log; diff tests/expected_report.txt phpcs.log
+  - vendor/bin/phpstan analyse
+  - vendor/bin/phpunit
 
 stages:
   - Validate against schema

composer.json

@@ -22,7 +22,7 @@
     ],
     "autoload": {
        "psr-4": {
-           "Doctrine\\Sniffs\\": "lib/Doctrine/Sniffs"
+           "Doctrine\\": "lib/Doctrine"
        }
     },
     "require": {
@@ -38,5 +38,14 @@
         "branch-alias": {
             "dev-master": "6.0.x-dev"
         }
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^7.2",
+        "phpstan/phpstan": "^0.10"
+    },
+    "autoload-dev": {
+        "psr-4": {
+           "Doctrine\\": "tests/Doctrine"
+        }
     }
 }

lib/Doctrine/Helpers/ClassHelper.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Helpers;
+
+use PHP_CodeSniffer\Files\File;
+
+class ClassHelper
+{
+    public static function isAbstract(File $phpcsFile, int $classPointer) : bool
+    {
+        return $phpcsFile->getClassProperties($classPointer)['is_abstract'];
+    }
+}

lib/Doctrine/Helpers/InheritanceHelper.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Helpers;
+
+use PHP_CodeSniffer\Files\File;
+use SlevomatCodingStandard\Helpers\TokenHelper;
+use const T_COMMA;
+use const T_EXTENDS;
+use const T_OPEN_CURLY_BRACKET;
+use function trim;
+
+class InheritanceHelper
+{
+    /**
+     * @return string[]
+     */
+    public static function getExtendedInterfaces(File $phpcsFile, int $pointer) : array
+    {
+        $limit = TokenHelper::findNext($phpcsFile, [T_OPEN_CURLY_BRACKET], $pointer) - 1;
+        $start = TokenHelper::findNext($phpcsFile, [T_EXTENDS], $pointer + 1, $limit);
+
+        if ($start === null) {
+            return [];
+        }
+
+        $extendedInterfaces = [];
+        do {
+            $localEnd             = TokenHelper::findNextLocal($phpcsFile, [T_COMMA], $start + 1, $limit) ?? $limit;
+            $extendedInterfaces[] = trim(TokenHelper::getContent($phpcsFile, $start + 1, $localEnd - 1));
+            $start                = $localEnd;
+        } while ($start < $limit);
+
+        return UseStatementHelper::getRealNames($phpcsFile, $pointer, $extendedInterfaces);
+    }
+
+    public static function classExtendsException(File $phpcsFile, int $pointer) : bool
+    {
+        $extendedName = $phpcsFile->findExtendedClassName($pointer);
+
+        if ($extendedName === false) {
+            return false;
+        }
+
+        return NamingHelper::hasExceptionSuffix(UseStatementHelper::getRealName($phpcsFile, $extendedName));
+    }
+}

lib/Doctrine/Helpers/NamingHelper.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Helpers;
+
+use Throwable;
+use function in_array;
+use function preg_match;
+
+final class NamingHelper
+{
+    public static function hasExceptionSuffix(string $className) : bool
+    {
+        return preg_match('~Exception$~', $className) === 1;
+    }
+
+    /**
+     * @param string[] $names
+     */
+    public static function containsException(array $names) : bool
+    {
+        foreach ($names as $name) {
+            if (! self::hasExceptionSuffix($name)) {
+                continue;
+            }
+
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * @param string[] $names
+     */
+    public static function containsThrowable(array $names) : bool
+    {
+        return in_array(Throwable::class, $names, true);
+    }
+}

lib/Doctrine/Helpers/UseStatementHelper.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Helpers;
+
+use PHP_CodeSniffer\Files\File;
+use SlevomatCodingStandard\Helpers\NamespaceHelper;
+use SlevomatCodingStandard\Helpers\UseStatementHelper as UseHelper;
+use function array_map;
+use function ltrim;
+use function sprintf;
+
+class UseStatementHelper
+{
+    /**
+     * @return string[]
+     */
+    public static function getUseStatements(File $phpcsFile) : array
+    {
+        $importedClasses = [];
+        foreach (UseHelper::getUseStatements($phpcsFile, 0) as $useStatement) {
+            $importedClasses[$useStatement->getNameAsReferencedInFile()] = $useStatement->getFullyQualifiedTypeName();
+        }
+
+        return $importedClasses;
+    }
+
+    /**
+     * @param string[] $referencedNames
+     *
+     * @return string[]
+     */
+    public static function getRealNames(File $phpcsFile, int $pointer, array $referencedNames) : array
+    {
+        $uses             = self::getUseStatements($phpcsFile);
+        $currentNamespace = NamespaceHelper::findCurrentNamespaceName($phpcsFile, $pointer);
+
+        return array_map(static function (string $extendedInterface) use ($uses, $currentNamespace) : string {
+            if ($extendedInterface[0] === '\\') {
+                return ltrim($extendedInterface, '\\');
+            }
+
+            if (isset($uses[$extendedInterface])) {
+                return ltrim($uses[$extendedInterface], '\\');
+            }
+
+            if ($currentNamespace === null) {
+                return $extendedInterface;
+            }
+
+            return sprintf('%s\\%s', $currentNamespace, $extendedInterface);
+        }, $referencedNames);
+    }
+
+    public static function getRealName(File $phpcsFile, string $referencedName) : string
+    {
+        $uses = self::getUseStatements($phpcsFile);
+        return $uses[$referencedName] ?? $referencedName;
+    }
+}

lib/Doctrine/Sniffs/Classes/ExceptionClassNamingSniff.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Sniffs\Classes;
+
+use Doctrine\Helpers\ClassHelper;
+use Doctrine\Helpers\InheritanceHelper;
+use Doctrine\Helpers\NamingHelper;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use const T_CLASS;
+use function assert;
+
+final class ExceptionClassNamingSniff implements Sniff
+{
+    public const CODE_NOT_EXTENDING_EXCEPTION = 'NotExtendingException';
+    public const CODE_MISSING_SUFFIX          = 'MissingSuffix';
+    public const CODE_SUPERFLUOUS_SUFFIX      = 'SuperfluousSuffix';
+
+    /**
+     * @return int[]|string[]
+     */
+    public function register() : array
+    {
+        return [T_CLASS];
+    }
+
+    /**
+     * @param int $pointer
+     *
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingParameterTypeHint
+     */
+    public function process(File $phpcsFile, $pointer) : void
+    {
+        $declarationName = $phpcsFile->getDeclarationName($pointer);
+        assert($declarationName !== null);
+
+        $isAbstract       = ClassHelper::isAbstract($phpcsFile, $pointer);
+        $extendsException = InheritanceHelper::classExtendsException($phpcsFile, $pointer);
+        $hasSuffix        = NamingHelper::hasExceptionSuffix($declarationName);
+
+        if (! $hasSuffix && ! $extendsException) {
+            // class Foo
+            // class Foo extends Bar
+            // abstract class Foo
+            // abstract class Foo extends Bar
+
+            return;
+        }
+
+        if (! $hasSuffix && ! $isAbstract && $extendsException) {
+            // class FooProblem extends BarException
+
+            return;
+        }
+
+        if ($hasSuffix && $isAbstract && $extendsException) {
+            // class FooException extends BarException
+
+            return;
+        }
+
+        if ($hasSuffix && $isAbstract && ! $extendsException) {
+            // abstract class FooException extends Bar
+
+            $phpcsFile->addError(
+                'Abstract exception must extend another exception.',
+                $pointer,
+                self::CODE_NOT_EXTENDING_EXCEPTION
+            );
+
+            return;
+        }
+
+        if (! $hasSuffix && $isAbstract && $extendsException) {
+            // class Foo extends BarException
+
+            $phpcsFile->addError(
+                'Abstract exceptions must use the "Exception" suffix.',
+                $pointer,
+                self::CODE_MISSING_SUFFIX
+            );
+
+            return;
+        }
+
+        assert($hasSuffix && ! $isAbstract);
+
+        // class FooException
+
+        $phpcsFile->addError(
+            'Leaf exception classes must not end with the "Exception" suffix.',
+            $pointer,
+            self::CODE_SUPERFLUOUS_SUFFIX
+        );
+    }
+}

lib/Doctrine/Sniffs/Classes/ExceptionInterfaceNamingSniff.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Sniffs\Classes;
+
+use Doctrine\Helpers\InheritanceHelper;
+use Doctrine\Helpers\NamingHelper;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use const T_INTERFACE;
+
+final class ExceptionInterfaceNamingSniff implements Sniff
+{
+    private const CODE_NOT_AN_EXCEPTION = 'NotAnException';
+
+    /**
+     * @return int[]|string[]
+     */
+    public function register() : array
+    {
+        return [T_INTERFACE];
+    }
+
+    /**
+     * @param int $pointer
+     *
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingParameterTypeHint
+     */
+    public function process(File $phpcsFile, $pointer) : void
+    {
+        $declarationName    = $phpcsFile->getDeclarationName($pointer);
+        $extendedInterfaces = InheritanceHelper::getExtendedInterfaces($phpcsFile, $pointer);
+        $extendsThrowable   = NamingHelper::containsThrowable($extendedInterfaces);
+        $hasSuffix          = NamingHelper::hasExceptionSuffix((string) $declarationName);
+
+        if ($hasSuffix && $extendsThrowable) {
+            // interface FooException extends Throwable
+            return;
+        }
+
+        // assumes that an interface with the "Exception" suffix is a valid exception interface
+        $extendsException = NamingHelper::containsException($extendedInterfaces);
+
+        if ($hasSuffix && $extendsException) {
+            // interface FooException extends BarException
+            return;
+        }
+
+        if ($hasSuffix && ! $extendsException && ! $extendsThrowable) {
+            // interface FooException
+            $phpcsFile->addError(
+                'Exception interface must extend another exception interface or Throwable.',
+                $pointer,
+                self::CODE_NOT_AN_EXCEPTION
+            );
+
+            return;
+        }
+
+        if (! $extendsException && ! $extendsThrowable) {
+            return;
+        }
+
+        // interface Foo extends Throwable
+        // interface Foo extends BarException
+        $phpcsFile->addError(
+            'Exception interface must end with the "Exception" name suffix.',
+            $pointer,
+            self::CODE_NOT_AN_EXCEPTION
+        );
+    }
+}

lib/Doctrine/ruleset.xml

@@ -119,8 +119,6 @@
     <rule ref="SlevomatCodingStandard.Classes.UnusedPrivateElements"/>
     <!-- Forbid suffix "Abstract" for abstract classes -->
     <rule ref="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming"/>
-    <!-- Forbid suffix "Exception" for exception classes -->
-    <rule ref="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming"/>
     <!-- Forbid suffix "Interface" for interfaces -->
     <rule ref="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming"/>
     <!-- Require specific order of phpDoc annotations with empty newline between specific groups -->
@@ -475,4 +473,6 @@
         <!-- turned off by PSR2 -> turning back on -->
         <severity>5</severity>
     </rule>
+
+
 </ruleset>