Search by

thesis / exceptionally

vudaltsov

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

Package info

github.com/thesis-php/exceptionally

Issues

pkg:composer/thesis/exceptionally

Fund package maintenance!

www.tinkoff.ru/cf/5MqZQas2dk7

Statistics

Installs: 2 040

Dependents: 4

Suggesters: 0

Stars: 9

v0.4.0 2026-11-17 02:42 UTC

This package is auto-updated.

Last update: 2026-11-19 05:05:04 UTC


README

Thesis Exceptionally

PHP Release License PHPStan Coverage

A read-only split of packages/exceptionally from the thesis-php/thesis monorepo: issues and pull requests go there.

Report a bug · Request a feature · Changelog · Contributing

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 PHP 8.6+. 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.