Shocm's Blog
• 7 min read

PHP 8.6 Gives Streams Real Errors, and You Can Finally Stop Parsing Warning Strings

PHP 8.6 adds StreamErrorMode, StreamError objects and stream_last_errors(), so a failed fopen() reports a typed code instead of a warning string.

php php-8-6 php-internals streams error-handling rfc
Featured image for "PHP 8.6 Gives Streams Real Errors, and You Can Finally Stop Parsing Warning Strings"

Every PHP codebase over a certain age has this function in it somewhere. Maybe it is called safeRead(), maybe it is a static method on a FileHelper nobody wants to own:

function safeRead(string $path): ?string
{
    $contents = @file_get_contents($path);

    if ($contents === false) {
        $error = error_get_last();

        if (str_contains($error['message'] ?? '', 'No such file')) {
            return null;
        }

        throw new RuntimeException($error['message'] ?? 'Unknown stream failure');
    }

    return $contents;
}

That str_contains() is the part that should bother you. The only way to tell “the file is not there” apart from “the file is there and you cannot read it” is to grep an English sentence that PHP was never contractually obliged to keep stable. Change the locale, change the wrapper, upgrade PHP, and your branch quietly stops matching.

PHP 8.6 fixes this. The Stream Error Handling Improvements RFC by Jakub Zelenka passed 25 to 1 with five abstentions in May and is marked implemented as of late August, which puts it comfortably inside the 8.6 branch ahead of the September 24 hard freeze.

Three context options

Everything hangs off the stream context, under a new root stream field. There are three options.

error_mode decides how errors surface. It takes a StreamErrorMode enum: Error (the current behavior, warnings and notices, still the default), Exception (terminating errors throw a StreamException), or Silent (nothing is emitted at all).

error_store decides which errors get kept for later retrieval, using a StreamErrorStore enum with cases Auto, None, NonTerminating, Terminating and All. Auto is the default and it does the sensible thing: under Error mode it stores nothing, under Exception mode it stores the non-terminating errors that did not throw, and under Silent mode it stores everything.

error_handler is an optional callback that receives an array of StreamError objects. It fires no matter which mode you picked, which makes it the right place to hang logging.

The terminating versus non-terminating distinction matters. A terminating error stopped the operation from completing, like a missing file or a denied permission. A non-terminating error is something PHP wants you to know about but which did not stop the work, like buffer truncation. Exception mode only throws for the terminating kind.

Exception mode

This is the version most application code will want:

$context = stream_context_create([
    'stream' => [
        'error_mode' => StreamErrorMode::Exception,
    ],
]);

try {
    $handle = fopen('/srv/phparch/issues/2026-09.pdf', 'r', false, $context);
} catch (StreamException $e) {
    $first = array_first($e->getErrors());

    if ($first?->code === StreamErrorCode::NotFound) {
        return $this->regenerateIssue();
    }

    throw $e;
}

StreamException::getErrors() returns an array of StreamError, and StreamError is a final readonly class with six properties: code (a StreamErrorCode enum case), message, wrapperName, severity (the usual E_WARNING and friends), terminating, and param, which is typically the filename or URL that failed.

The code property is the whole point. StreamErrorCode ships with more than seventy cases covering the things that actually go wrong: NotFound, PermissionDenied, AlreadyExists, ReadFailed, WriteFailed, SeekNotSupported, ConnectFailed, RedirectLimit, AuthFailed, InvalidUrl, LockFailed, WrapperNotFound, and a long tail of wrapper-specific conditions. You compare enum cases instead of substrings.

Silent mode, when you do not want exceptions

Not every failed read deserves a stack unwind. Cache lookups, for example, expect misses:

$context = stream_context_create([
    'stream' => [
        'error_mode'  => StreamErrorMode::Silent,
        'error_store' => StreamErrorStore::All,
    ],
]);

$cached = @fopen($cachePath, 'r', false, $context);

if ($cached === false) {
    $error = array_first(stream_last_errors());

    if ($error?->code === StreamErrorCode::NotFound) {
        $cached = $this->warm($cachePath);
    } else {
        $this->logger->warning('Cache read failed', [
            'code'    => $error?->code->name,
            'wrapper' => $error?->wrapperName,
            'path'    => $error?->param,
        ]);
    }
}

stream_last_errors() returns the errors from the most recent operation that stored anything, ordered with the primary error first. It replaces the previous result on every storable operation, so you do not need to clear between calls. There is a stream_clear_errors() if you want to discard them explicitly, but it is a housekeeping tool rather than a correctness requirement.

array_first() is the PHP 8.5 addition, which pairs nicely here. If you are still on 8.4 semantics in your head, $errors[0] ?? null does the same job.

Errors come in groups

This is the part I did not expect and now find obvious. One stream call can fail for more than one reason, and PHP 8.6 keeps all of them.

The RFC’s own example is stream_select() on a userspace stream. The select fails because stream_cast() is not implemented, and then it fails again because the stream cannot be represented as a file descriptor. Both are real, both are terminating, and both end up in the array:

$errors = stream_last_errors();

foreach ($errors as $error) {
    echo $error->code->name . ': ' . $error->message . PHP_EOL;
}

if (array_any($errors, fn ($e) => $e->code === StreamErrorCode::CastNotSupported)) {
    echo 'This stream cannot be used with select()' . PHP_EOL;
}

Because it is a plain array, array_find(), array_any() and array_filter() all work on it. An earlier draft of the RFC used a linked list with a next property, and version 2.2 replaced that with arrays. If you read a write-up from earlier in the year that mentioned stream_get_last_error() returning a chained object, that API is gone.

Four functions gained a context parameter

You cannot configure error handling on a call that never accepted a context, so the RFC added one to four functions that were missing it:

  • stream_select() picks up a sixth argument
  • stream_copy_to_stream() picks up a fifth
  • stream_socket_pair() picks up a fourth
  • stream_is_local() picks up a second

All optional, all defaulting to null. This is what makes the stream_select() example above possible at all.

$context = stream_context_create([
    'stream' => ['error_mode' => StreamErrorMode::Exception],
]);

try {
    $src = fopen('phptek://schedule.json', 'r', false, $context);
    $dst = fopen('/tmp/schedule.json', 'w', false, $context);
    stream_copy_to_stream($src, $dst, null, 0, $context);
} catch (StreamException $e) {
    $this->logger->error('Copy failed', ['errors' => $e->getErrors()]);
}

The gotcha worth knowing

You cannot set error_mode, error_store or error_handler on the default context. Passing any of them to stream_context_set_default() throws a ValueError.

That restriction is deliberate and, honestly, correct. Flipping every stream in the process to exception mode would break any library that quietly relies on @fopen() returning false with a warning, and you would have no way to know which of your vendor directory that includes. Error handling has to be configured through an explicit context you created and passed in, which means it only ever applies to calls you own.

What this means for existing code

Nothing breaks. StreamErrorMode::Error is the default and preserves the current warning and notice behavior exactly.

The RFC lists three minor changes worth reading if you have unusual stream code. Some errors that were previously reported incorrectly have been fixed. Context is now properly propagated to child streams. And error reporting happens closer to the function’s return, which can reorder stream errors relative to non-stream errors emitted in the same call. If you have a test suite asserting on the exact sequence of warnings, that last one is the plausible source of a surprise.

When you can use it

PHP 8.6 Beta 1 landed August 13, 2026. RC1 is scheduled for September 24, which is the hard freeze, and general availability is targeted for November 19. Those dates are intentions rather than promises, but the feature itself is already in the branch.

One caveat if you go testing the beta. The RFC is explicit that the implementation still needs further conversions and grouping blocks across the codebase, so not every stream error site is wired into the new system yet. Hit an unconverted wrapper and you will get an old-style error, or a group with fewer entries than you expected. The API is settled; the coverage behind it is still being filled in.

The realistic timeline for most applications is that you will be on 8.6 sometime in 2027, and by then a Filesystem or HttpClient wrapper in your framework of choice has probably already adopted this internally. Which is fine. The libraries are exactly who needed it most, because they are the ones currently shipping their own str_contains($message, 'No such file') and hoping.

If you maintain one of those libraries, install the beta against your test suite now. The window where a bug report can still change the implementation closes on September 24.

Sources: PHP RFC: Stream Error Handling Improvements, Stream Error Handling Improvements on PHP.Watch, PHP 8.6 RFC List, PHP.Watch, PHP 8.6’s soft feature freeze, PHP Architect, php-src PR #20524.