Turns PHP errors into exceptions around a callable. Safe when the callable suspends a fiber.
use function Thesis\exceptionally;
// throws \ErrorException instead of a warning and false
$content = exceptionally(static fn() => file_get_contents('/path/to/file'));composer require thesis/exceptionallyRequires 64-bit PHP 8.5+. No extensions.
Many functions of PHP fail with a warning and false. exceptionally() throws the warning
as an \ErrorException with its message, level
(getSeverity()), file and line.
false is a failure too, so the result type has no false: string above, true for bool. When the function
returns false and no error was thrown (suppressed, at another level, swallowed by another handler or none),
exceptionally() throws an \ErrorException of E_WARNING.
So false as an answer throws too: fgets() and readdir() at the end, flock() with LOCK_NB,
unserialize() and json_decode() of a false. Return something else instead:
$line = exceptionally(static function () use ($handle) {
$line = fgets($handle);
return $line === false ? null : $line; // null at the end, a warning is still thrown
});A generator function returns its generator before its body runs: call exceptionally() inside the body.
By default every level except E_DEPRECATED and E_USER_DEPRECATED is thrown: deprecations usually come
from other libraries and should not stop the code. The second argument sets the levels:
exceptionally($fn, E_USER_WARNING | E_USER_NOTICE);
exceptionally($fn, E_ALL); // deprecations tooAn error at another level goes to the previous error handler, but a false after it is thrown.
In nested calls the innermost one decides.
An error suppressed with @, around the function or the call, or by the error_reporting ini setting
goes to the previous handler. The false after it is still thrown:
exceptionally(static fn() => @file_get_contents('/path/to/file')); // throws: returned false and no error was thrownAs in PHP, @ does not suppress E_USER_ERROR and E_RECOVERABLE_ERROR.
The function may suspend the fiber, for example to wait for I/O. Errors of other fibers, including the ones started inside the function, are not thrown: they go to the previous handler.
The error handlers of PHP form one stack for all fibers. exceptionally() takes off only its own handlers,
and only from the top. So:
- A handler set while the function runs (by the function or by another fiber while it is suspended) stays. It gets the errors first, and they are thrown only if it passes them on. Set the handler of the application before such calls start.
- Do not restore a handler set before a call while the call runs:
restore_error_handler()takes off the handler ofexceptionally()instead, its errors are not thrown anymore, and the handler you meant stays. - The previous handler must not suspend the fiber: while a handler runs, PHP has none, and if another fiber
sets one meanwhile, PHP forgets the running one. This breaks with or without
exceptionally(). exit()and a fatal error do not finish the call: errors of the shutdown functions at its levels are thrown.