Skip to content

Commit eb8456c

Browse files
beberleibeberlei
committed
Rework Exception Naming Conventions
Until now the SuperfluousExceptionNaming sniff was enabled in Doctrine Coding Standard, but every of our projects disabled this sniff in their local phpcs.xml rule. Doctrine does not actually follow this rule, instead we provide the context of the exception in the name as a "prefix" similar to PHPs own RuntimeException and so on. This is done, because exceptions are used soley in the context of code that reads like: } catch (DBALException $e) { } If we allow classes named "Exception", then we introduce a developer experience problem, because it potentially requires the user to make an alias/renaming decision, increasing their mental load: use OtherLibrary\Exception as OtherException; use Doctrine\DBAL\Exception as DBALException; use Exception; } catch (OtherException $e) { } catch (DBALException $e) { } catch (Exception $e) { } Additionally it makes it hard for developers understanding catch clauses when they cannot rely on the fact that "Exception" is the global one. } catch (Exception $e) { // don't mess with user expectations
1 parent 637003f commit eb8456c

File tree

6 files changed

+82
-7
lines changed

6 files changed

+82
-7
lines changed

‎lib/Doctrine/Sniffs/NamingConventions/ExceptionNamingSniff.php‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\Sniffs\NamingConventions;
6+
7+
use PHP_CodeSniffer\Files\File;
8+
use PHP_CodeSniffer\Sniffs\Sniff;
9+
10+
use function trim;
11+
use function ucfirst;
12+
13+
use const T_CLASS;
14+
use const T_STRING;
15+
16+
class ExceptionNamingSniff implements Sniff
17+
{
18+
/**
19+
* @return array<int, (int|string)>
20+
*
21+
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
22+
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint
23+
*/
24+
public function register()
25+
{
26+
return [T_CLASS];
27+
}
28+
29+
/**
30+
* @param int $stackPtr
31+
*
32+
* @return void
33+
*
34+
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
35+
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint
36+
*/
37+
public function process(File $phpcsFile, $stackPtr)
38+
{
39+
$tokens = $phpcsFile->getTokens();
40+
41+
$className = $phpcsFile->findNext(T_STRING, $stackPtr);
42+
$name = trim($tokens[$className]['content']);
43+
$errorData = [ucfirst($tokens[$stackPtr]['content'])];
44+
45+
switch ($name) {
46+
case 'Exception':
47+
$phpcsFile->addError(
48+
'Using Exception as a short class name is not allowed.',
49+
$stackPtr,
50+
'Invalid',
51+
$errorData
52+
);
53+
break;
54+
}
55+
}
56+
}

‎lib/Doctrine/ruleset.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,6 @@
147147
<rule ref="SlevomatCodingStandard.Classes.UnusedPrivateElements"/>
148148
<!-- Forbid prefix and suffix "Abstract" for abstract classes -->
149149
<rule ref="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming"/>
150-
<!-- Forbid prefix and suffix "Exception" for exception classes -->
151-
<rule ref="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming"/>
152150
<!-- Forbid prefix and suffix "Interface" for interfaces -->
153151
<rule ref="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming"/>
154152
<!-- Forbid suffix "Trait" for traits -->
@@ -557,4 +555,6 @@
557555
<!-- turned off by PSR-12 -> turning back on -->
558556
<severity>5</severity>
559557
</rule>
558+
559+
<rule ref="Doctrine.NamingConventions.ExceptionNaming"/>
560560
</ruleset>

‎tests/expected_report.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ tests/input/doc-comment-spacing.php 10 0
1616
tests/input/duplicate-assignment-variable.php 1 0
1717
tests/input/EarlyReturn.php 6 0
1818
tests/input/example-class.php 36 0
19+
tests/input/exception-naming.php 2 0
1920
tests/input/forbidden-comments.php 14 0
2021
tests/input/forbidden-functions.php 6 0
2122
tests/input/inline_type_hint_assertions.php 7 0
@@ -35,7 +36,7 @@ tests/input/semicolon_spacing.php 3 0
3536
tests/input/single-line-array-spacing.php 5 0
3637
tests/input/spread-operator.php 6 0
3738
tests/input/static-closures.php 1 0
38-
tests/input/superfluous-naming.php 11 0
39+
tests/input/superfluous-naming.php 10 0
3940
tests/input/test-case.php 8 0
4041
tests/input/trailing_comma_on_array.php 1 0
4142
tests/input/traits-uses.php 11 0
@@ -45,7 +46,7 @@ tests/input/use-ordering.php 1 0
4546
tests/input/useless-semicolon.php 2 0
4647
tests/input/UselessConditions.php 20 0
4748
----------------------------------------------------------------------
48-
A TOTAL OF 375 ERRORS AND 0 WARNINGS WERE FOUND IN 41 FILES
49+
A TOTAL OF 376 ERRORS AND 0 WARNINGS WERE FOUND IN 42 FILES
4950
----------------------------------------------------------------------
5051
PHPCBF CAN FIX 310 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
5152
----------------------------------------------------------------------

‎tests/fixed/exception-naming.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Test;
6+
7+
class Exception
8+
{
9+
}

‎tests/input/exception-naming.php‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Test;
6+
7+
class Exception
8+
{
9+
}

‎tests/php-compatibility.patch‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ index fd5432c..233e24d 100644
88
tests/input/EarlyReturn.php 6 0
99
-tests/input/example-class.php 36 0
1010
+tests/input/example-class.php 39 0
11+
tests/input/exception-naming.php 2 0
1112
tests/input/forbidden-comments.php 14 0
1213
tests/input/forbidden-functions.php 6 0
13-
tests/input/inline_type_hint_assertions.php 7 0
1414
@@ -23,9 +23,9 @@ tests/input/LowCaseTypes.php 2 0
1515
tests/input/namespaces-spacing.php 7 0
1616
tests/input/NamingCamelCase.php 7 0
@@ -34,8 +34,8 @@ index fd5432c..233e24d 100644
3434
tests/input/useless-semicolon.php 2 0
3535
tests/input/UselessConditions.php 20 0
3636
----------------------------------------------------------------------
37-
-A TOTAL OF 375 ERRORS AND 0 WARNINGS WERE FOUND IN 41 FILES
38-
+A TOTAL OF 384 ERRORS AND 0 WARNINGS WERE FOUND IN 41 FILES
37+
-A TOTAL OF 376 ERRORS AND 0 WARNINGS WERE FOUND IN 42 FILES
38+
+A TOTAL OF 385 ERRORS AND 0 WARNINGS WERE FOUND IN 42 FILES
3939
----------------------------------------------------------------------
4040
-PHPCBF CAN FIX 310 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
4141
+PHPCBF CAN FIX 319 OF THESE SNIFF VIOLATIONS AUTOMATICALLY

0 commit comments

Comments
 (0)