pepakriz / phpstan-exception-rules
Exception rules for PHPStan
Installs: 2 086 417
Dependents: 34
Suggesters: 0
Security: 0
Stars: 108
Watchers: 7
Forks: 9
Open Issues: 8
Type:phpstan-extension
Requires
- php: >=7.1
- nikic/php-parser: ^4.13
- phpstan/phpstan: ^1.0
Requires (Dev)
- nette/utils: ^3.0
- php-parallel-lint/php-console-highlighter: ^0.4.0
- php-parallel-lint/php-parallel-lint: ^1.2.0
- phpstan/phpstan-nette: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpstan/phpstan-strict-rules: ^1.0
- phpunit/phpunit: ^7.5.6 || ^9.4.2
- slevomat/coding-standard: ^6.4.1
- squizlabs/php_codesniffer: ~3.5.2
- dev-master / 0.12.x-dev
- v0.12.0
- v0.11.7
- v0.11.6
- v0.11.5
- v0.11.4
- v0.11.3
- v0.11.2
- v0.11.1
- v0.11.0
- v0.10.1
- v0.10.0
- v0.9.0
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.3
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.0
- v0.4.4
- v0.4.3
- v0.4.2
- v0.4.1
- v0.4.0
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.0
- v0.1.1
- v0.1.0
- dev-VincentLanglet-patch-1
- dev-pk/remove-php71-support
- dev-master-build-fix
- dev-php-7.3-support
- dev-scope
- dev-catch-and-throw
This package is auto-updated.
Last update: 2024-12-12 16:48:45 UTC
README
This extension provides following rules and features:
- Require
@throws
annotation when some checked exception is thrown (examples) - Exception propagation over:
- Ignore caught checked exceptions (examples)
- Unnecessary
@throws
annotation detection (examples) - Useless
@throws
annotation detection (examples) - Optionally allows unused
@throws
annotations in subtypes (examples) @throws
annotation variance validation (examples)- Dynamic throw types based on arguments
- Unreachable catch statements
- Report throwing checked exceptions in the global scope (examples)
Features and rules provided by PHPStan core (we rely on):
@throws
annotation must contain only validThrowable
types- Thrown value must be subclass of
Throwable
Usage
To use this extension, require it in Composer:
composer require --dev pepakriz/phpstan-exception-rules
And include and configure extension.neon in your project's PHPStan config:
includes: - vendor/pepakriz/phpstan-exception-rules/extension.neon parameters: exceptionRules: reportUnusedCatchesOfUncheckedExceptions: false reportUnusedCheckedThrowsInSubtypes: false reportCheckedThrowsInGlobalScope: false checkedExceptions: - RuntimeException
You could use uncheckedExceptions
when you prefer a list of unchecked exceptions instead. It is a safer variant, but harder to adapt to the existing project.
parameters: exceptionRules: uncheckedExceptions: - LogicException - PHPUnit\Framework\Exception
checkedExceptions
anduncheckedExceptions
cannot be configured at the same time
If some third-party code defines wrong throw types (or it doesn't use @throws annotations at all), you could override definitions like this:
parameters: exceptionRules: methodThrowTypeDeclarations: FooProject\SomeService: sendMessage: - FooProject\ConnectionTimeoutException methodWithoutException: [] functionThrowTypeDeclarations: myFooFunction: - FooException
In some cases, you may want to ignore exception-related errors as per class basis, as is usually the case for testing:
parameters: exceptionRules: methodWhitelist: PHPUnit\Framework\TestCase: '#^(test|(setup|setupbeforeclass|teardown|teardownafterclass)$)#i'
Extensibility
Dynamic throw type extensions
- If the throw type is not always the same, but depends on an argument passed to the method. (Similar feature as Dynamic return type extensions)
There are interfaces, which you can implement:
Pepakriz\PHPStanExceptionRules\DynamicMethodThrowTypeExtension
- service tag:exceptionRules.dynamicMethodThrowTypeExtension
Pepakriz\PHPStanExceptionRules\DynamicStaticMethodThrowTypeExtension
- service tag:exceptionRules.dynamicStaticMethodThrowTypeExtension
Pepakriz\PHPStanExceptionRules\DynamicConstructorThrowTypeExtension
- service tag:exceptionRules.dynamicConstructorThrowTypeExtension
Pepakriz\PHPStanExceptionRules\DynamicFunctionThrowTypeExtension
- service tag:exceptionRules.dynamicFunctionThrowTypeExtension
and register as service with correct tag:
services: - class: App\PHPStan\EntityManagerDynamicMethodThrowTypeExtension tags: - exceptionRules.dynamicMethodThrowTypeExtension
Motivation
There are 2 types of exceptions:
- Safety-checks that something should never happen (you should never call some method in some case etc.). We call these LogicException and if they are thrown, programmer did something wrong. For that reason, it is important that this exception is never caught and kills the application. Also, it is important to write good descriptive message of what went wrong and how to fix it - that is why every LogicException must have a message. Therefore, inheriting LogicException does not make much sense. Also, LogicException should never be
@throws
annotation (see below). - Special cases in business logic which should be handled by application and error cases that just may happen no matter how hard we try (e.g. HTTP request may fail). These exceptions we called RuntimeException or maybe better "checked exception". All these exceptions should be checked. Therefore it must be either caught or written in
@throws
annotation. Also if you call an method with that annotation and do not catch the exception, you must propagate it in your@throws
annotation. This, of course, may spread quickly. When this exception is handled (caught), it is important for programmer to immediately know what case is handled and therefore all used RuntimeExceptions are inherited from some parent and have very descriptive class name (so that you can see it in catch construct) - for exampleCannotCloseAccountWithPositiveBalanceException
. The message is not that important since you should always catch these exceptions somewhere, but in our case we often use that message in API output and display it to end-user, so please use something informative for users in that cases (you can pass custom arguments to constructor (e.g. entities) to provide better message). Sometimes you can meet a place where you know that some exception will never be thrown - in this case you can catch it and wrap to LogicException (because when it is thrown, it is a programmer's fault).
It is always a good idea to wrap previous exception so that we do not lose information of what really happened in some logs.
// no throws annotation public function decide(int $arg): void { switch ($arg) { case self::ONE: $this->decided() case self::TWO: $this->decidedDifferently() default: throw new LogicException("Decision cannot be made for argument $arg because of ..."); } } /** * @return mixed[] * * @throws PrintJobFailedException */ private function sendRequest(Request $request): array { try { $response = $this->httpClient->send($request); return Json::decode((string) $response->getBody(), Json::FORCE_ARRAY); } catch (GuzzleException | JsonException $e) { throw new PrintJobFailedException($e); } } class PrintJobFailedException extends RuntimeException { public function __construct(Throwable $previous) { parent::__construct('Printing failed, remote printing service is down. Please try again later', $previous); } }
Known limitations
Anonymous functions are analyzed at the same place they are declared
False positive when a method does not execute declared function:
/** * @throws FooRuntimeException false positive */ public function createFnFoo(int $arg): callable { return function () { throw new FooRuntimeException(); }; }
But most of use-cases just works:
/** * @param string[] $rows * @return string[] * * @throws EmptyLineException */ public function normalizeRows(array $rows): array { return array_map(function (string $row): string { $row = trim($row); if ($row === '') { throw new EmptyLineException(); } return $row; }, $rows); }
Catch
statement does not know about runtime subtypes
This case is detected by rule, so you will be warned about a potential risk.
Runtime exception is absorbed:
// @throws phpdoc is not required public function methodWithoutThrowsPhpDoc(): void { try { throw new RuntimeException(); $this->dangerousCall(); } catch (Throwable $e) { throw $e; } }
As a workaround you could use custom catch statement:
/** * @throws RuntimeException */ public function methodWithThrowsPhpDoc(): void { try { throw new RuntimeException(); $this->dangerousCall(); } catch (RuntimeException $e) { throw $e; } catch (Throwable $e) { throw $e; } }