d3cfe19d7e
Co-authored-by: Marco Borgeaud <89914223+marco-antognini-sonarsource@users.noreply.github.com>
57 lines
2.2 KiB
Plaintext
57 lines
2.2 KiB
Plaintext
This rule raises an issue when a generic exception (such as `ErrorException`, `RuntimeException` or `Exception`) is thrown.
|
|
|
|
== Why is this an issue?
|
|
|
|
Throwing generic exceptions such as ``++Error++``, ``++RuntimeException++``, ``++Throwable++``, and ``++Exception++`` will have a negative impact on any code trying to catch these exceptions.
|
|
|
|
From a consumer perspective, it is generally a best practice to only catch exceptions you intend to handle. Other exceptions should ideally be let to propagate up the stack trace so that they can be dealt with appropriately. When a generic exception is thrown, it forces consumers to catch exceptions they do not intend to handle, which they then have to re-throw.
|
|
|
|
Besides, when working with a generic type of exception, the only way to distinguish between multiple exceptions is to check their message, which is error-prone and difficult to maintain. Legitimate exceptions may be unintentionally silenced and errors may be hidden.
|
|
|
|
When throwing an exception, it is therefore recommended to throw the most specific exception possible so that it can be handled intentionally by consumers.
|
|
|
|
== How to fix it
|
|
|
|
To fix this issue, make sure to throw specific exceptions that are relevant to the context in which they arise. It is recommended to either:
|
|
|
|
* Throw a subtype of `Exception` that already exists in the Standard PHP Library. For instance ``++InvalidArgumentException++`` could be raised when an unexpected argument is provided to a function.
|
|
* Define a custom exception type that derives from ``++Exception++`` or one of its subclasses.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,php,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
function checkValue($value) {
|
|
if ($value == 42) {
|
|
throw new Exception("Value is 42"); // Noncompliant: This will be difficult for consumers to handle
|
|
}
|
|
}
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,php,diff-id=1,diff-type=compliant]
|
|
----
|
|
function checkValue($value) {
|
|
if ($value == 42) {
|
|
throw new UnexpectedValueException("Value is 42"); // Compliant
|
|
}
|
|
}
|
|
----
|
|
|
|
include::../see.adoc[]
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
include::../message.adoc[]
|
|
|
|
'''
|
|
|
|
endif::env-github,rspecator-view[]
|