https://sandfox.me/tags/good-practices.xml 2026-01-05T10:06:10Z Anton Smirnov Nikola https://sandfox.me/php/do-not-use-exception.html 2025-10-09T20:57:00+03:00 2024-11-18T23:08:00+02:00 Anton Smirnov

<aside class="admonition note"> <p class="admonition-title">Note</p> <p>This post is slightly outdated and needs to be revised to align with PHP's internal policies. <a class="reference external" href="https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables">https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables</a></p> <p>While they are aimed at extensions, userspace libraries should benefit from them too.</p> </aside> <p>It is a bad practice to use the <code class="docutils literal">Exception</code> class directly in PHP. That means 2 points:</p> <ul class="simple"> <li><p>Do not throw <code class="docutils literal">Exception</code> directly</p></li> <li><p>Do not catch <code class="docutils literal">Exception</code> directly</p></li> </ul> <p>Subclassing <code class="docutils literal">Exception</code> is not a direct use in this context.</p> <section id="do-not-throw-exception"> <h2>Do not throw <code class="docutils literal">Exception</code></h2> <p>There are a lot of specific <code class="docutils literal">Exception</code> descendants in PHP. <a class="reference external" href="https://www.php.net/manual/en/spl.exceptions.php">See documentation for the full list.</a> It's not necessary to use and remember all of them, many have unclear use cases, but at very least you should separate your exceptions into <code class="docutils literal">RuntimeException</code> and <code class="docutils literal">LogicException</code>. As the doc says, <code class="docutils literal">LogicException</code> means code misuse. Throw <code class="docutils literal">LogicException</code> in cases when the upstream must be fixed because it uses your code incorrectly. Throw <code class="docutils literal">RuntimeException</code> in cases that are not predictable by the upstream, like service failures or invalid user input.</p> <p>In case you use exceptions for flow control, you need your own custom exceptions anyway. In this case you can extend the base <code class="docutils literal">Exception</code>, extending <code class="docutils literal">Exception</code> directly is not a sin, especially if your exceptions are not error conditions.</p> </section> <section id="do-not-catch-exception"> <h2>Do not catch <code class="docutils literal">Exception</code></h2> <p>Assuming you follow the previous point, there is no need to catch <code class="docutils literal">Exception</code>'s.</p> <ol class="arabic simple"> <li><p>If you don't guard against a specific situation, catch all <code class="docutils literal">RuntimeException</code>'s. <code class="docutils literal">LogicException</code>'s should go to your logger.</p></li> <li><p>In a global error handler that writes your logs, you need to catch Errors too, so you need to go even further and catch <code class="docutils literal">Throwable</code>.</p></li> <li><p>If you use exceptions for flow control (please don't haha) you already catching your own exceptions, and if you follow the previous point, they are already separated from actual error conditions and won't be caught mistakenly by a wrong level.</p></li> </ol> <p>Notable exceptions to the rule:</p> <ul class="simple"> <li><p>You use PHP below 7.0 and don't have <code class="docutils literal">Throwable</code>. Well, it's 2024 already so this is another call for you to upgrade. Otherwise assume point 2 allows you to catch a base <code class="docutils literal">Exception</code>.</p></li> <li><p>You use a library that throws plain <code class="docutils literal">Exception</code> instances. Well, bad for you, but maybe it's a good idea to report this thing as a problem.</p></li> </ul> </section>