Download the PHP package pepakriz/phpstan-exception-rules without Composer

PHPStan exception rules

• PHPStan

This extension provides following rules and features:

• Require @throws annotation when some checked exception is thrown (examples)
• Exception propagation over:
  • Function calls
  • Magic, dynamic and static method calls
  • Iterable interface in foreach and in iterator_*() functions (examples)
  • Countable interface combinated with count() function (examples)
  • JsonSerializable interface combinated with json_encode() function (examples)
• 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
  • exception has been caught in some previous catch statement (examples)
  • exception has been caught twice in the same catch statement (examples)
  • checked exception is never thrown in the corresponding try block (examples)
• Report throwing checked exceptions in the global scope (examples)

Features and rules provided by PHPStan core (we rely on):

• @throws annotation must contain only valid Throwable types
• Thrown value must be subclass of Throwable

Usage

To use this extension, require it in Composer:

And include and configure extension.neon in your project's PHPStan config:

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.

checkedExceptions and uncheckedExceptions 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:

In some cases, you may want to ignore exception-related errors as per class basis, as is usually the case for testing:

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:

Motivation

There are 2 types of exceptions:

1) 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). 2) 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 example CannotCloseAccountWithPositiveBalanceException. 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.

Known limitations

Anonymous functions are analyzed at the same place they are declared

False positive when a method does not execute declared function:

But most of use-cases just works:

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:

As a workaround you could use custom catch statement: