PHP stream_notification_callback() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_notification_callback() documents the callback signature used with the notification parameter of a stream context. It is a prototype, not a standalone function you normally call yourself.

You write a function (or closure) with these six parameters, then attach it through stream_context_set_params() using the notification key. During supported transfers (commonly http and ftp), PHP calls your callback with progress and status updates.

Syntax

Call stream_notification_callback() with the values you need. Start with this line.

PHP
stream_context_set_params($ctx, ["notification" => $callback]);
CallWhat it does
stream_context_set_params($ctx, ["notification" => "my_notify"])Wires a named function matching the callback signature.
stream_context_set_params($ctx, ["notification" => $fn])Wires a closure or other callable the same way.
stream_context_get_params($ctx)Shows the attached notification callable among context params.

PHP's manual lists stream_notification_callback as the shape your notifier must follow. Notifications are wrapper-specific; file and php:// streams typically will not fire them. Keep demos offline by attaching the callback and inspecting context params, or by calling your own function directly to show the arguments.

Library declarations
PHP
stream_notification_callback(int $notification_code, int $severity, ?string $message, int $message_code, int $bytes_transferred, int $bytes_max): void

Parameters

ParameterDescription
notification_codeRequired. One of the STREAM_NOTIFY_* constants describing the event.
severityRequired. One of the STREAM_NOTIFY_SEVERITY_* constants.
messageOptional message string for the event, or null when none is provided.
message_codeWrapper-specific message code related to the event.
bytes_transferredBytes transferred so far when the event reports progress.
bytes_maxMaximum bytes expected when the wrapper knows the size.

Return Value

Return ValueDescription
voidNotification callbacks do not return a value.

PHP Examples

Example 1 — Attach a Notification Callback to a Context

Create a context, set a notification closure, then read it back with stream_context_get_params().

PHP
<?php
$log = [];
$ctx = stream_context_create();

$notifier = function (
    int $code,
    int $severity,
    ?string $message,
    int $message_code,
    int $bytes_transferred,
    int $bytes_max
) use (&$log): void {
    $log[] = $code;
};

stream_context_set_params($ctx, ["notification" => $notifier]);
$params = stream_context_get_params($ctx);

echo isset($params["notification"]) ? "notification set" : "missing", PHP_EOL;
echo "events so far: ", count($log), PHP_EOL;

How It Works

  1. stream_context_create() builds an empty context.
  2. A closure matching the six-parameter signature is stored in $notifier.
  3. stream_context_set_params() attaches it under the notification key.
  4. No transfer ran, so the log is still empty, but get_params shows the callback is registered.

Example 2 — Call Your Notifier Yourself for Learning

Invoke the same shaped callback manually to see how progress arguments look, without using the network.

PHP
<?php
function demo_notify(
    int $notification_code,
    int $severity,
    ?string $message,
    int $message_code,
    int $bytes_transferred,
    int $bytes_max
): void {
    echo "code=", $notification_code, PHP_EOL;
    echo "transferred=", $bytes_transferred, "/", $bytes_max, PHP_EOL;
    echo "message=", $message ?? "(none)", PHP_EOL;
}

demo_notify(STREAM_NOTIFY_PROGRESS, STREAM_NOTIFY_SEVERITY_INFO, "demo", 0, 40, 100);

How It Works

  1. demo_notify() uses the documented parameter list.
  2. We call it directly with STREAM_NOTIFY_PROGRESS and sample byte counts.
  3. The printed code value is the integer for STREAM_NOTIFY_PROGRESS on PHP (7).
  4. This teaches the signature offline; real wrappers call you during a transfer.

Example 3 — Switch on Notification Constants

Show a small dispatcher that labels a few STREAM_NOTIFY_* codes.

PHP
<?php
function label_notify(int $code): string {
    switch ($code) {
        case STREAM_NOTIFY_CONNECT:
            return "connect";
        case STREAM_NOTIFY_PROGRESS:
            return "progress";
        case STREAM_NOTIFY_FAILURE:
            return "failure";
        default:
            return "other";
    }
}

echo label_notify(STREAM_NOTIFY_CONNECT), PHP_EOL;
echo label_notify(STREAM_NOTIFY_PROGRESS), PHP_EOL;
echo label_notify(STREAM_NOTIFY_FAILURE), PHP_EOL;

How It Works

  1. STREAM_NOTIFY_* constants identify event kinds passed as $notification_code.
  2. A switch maps a few common codes to short labels.
  3. Your real callback can use the same pattern to log or update a progress bar.
  4. Wire that callback with stream_context_set_params() when you are ready for live transfers.

Frequently Asked Questions

It is documented as the callback prototype for context notifications. You implement a callable with that signature and register it; PHP invokes it during supported transfers.
Create a stream context, then call stream_context_set_params($ctx, ["notification" => $callable]). Pass $ctx into the stream operation.
They are mainly useful with wrappers such as http and ftp. Many local wrappers never call the notifier.
Six values: notification code, severity, optional message, message code, bytes transferred, and bytes max.
Use stream_context_get_params($ctx) and look for the notification entry in the returned array.

Next: stream_register_wrapper()

stream_register_wrapper() registers a custom stream wrapper class under a protocol name so.

stream_register_wrapper() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful