Skip to content

About

Turns PHP errors into exceptions around a callable, safe when the callable suspends a fiber.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Thesis Exceptionally

PHP Version Requirement GitHub Release

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'));

Installation

composer require thesis/exceptionally

Requires 64-bit PHP 8.5+. No extensions.

Why

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.

Levels

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 too

An error at another level goes to the previous error handler, but a false after it is thrown. In nested calls the innermost one decides.

Suppressed errors

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 thrown

As in PHP, @ does not suppress E_USER_ERROR and E_RECOVERABLE_ERROR.

Fibers

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.

Other error handlers

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 of exceptionally() 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.

About

Turns PHP errors into exceptions around a callable, safe when the callable suspends a fiber.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages