PHP stream_wrapper_register() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_wrapper_register() registers a custom protocol scheme handled by a user-defined stream wrapper class.

After registration, URLs like mystore://item can be opened with fopen() and related functions. Provide the protocol name and the class name that implements the wrapper methods. stream_register_wrapper() is an alias.

Syntax

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

PHP
$ok = stream_wrapper_register('demo', DemoStream::class);
CallWhat it does
stream_wrapper_register('demo', 'DemoStream')Registers the demo:// scheme with class DemoStream.
stream_wrapper_register('demo', DemoStream::class)Same registration using ::class.
stream_wrapper_register('demo', 'DemoStream', STREAM_IS_URL)Registers the scheme and marks it as a URL wrapper.

The class needs stream wrapper methods such as stream_open() and stream_read(). Registration fails if the protocol is already taken. Use stream_wrapper_unregister() or stream_wrapper_restore() when replacing a built-in scheme temporarily.

Library declarations
PHP
stream_wrapper_register(string $protocol, string $class, int $flags = 0): bool

Parameters

ParameterDescription
protocolRequired. The scheme name without ://, such as demo.
classRequired. The class that implements the stream wrapper.
flagsOptional. 0 by default, or STREAM_IS_URL for URL-like wrappers.

Return Value

Return ValueDescription
trueThe protocol was registered.
falseRegistration failed (unknown class or protocol already exists).

PHP Examples

Example 1 — Register a Tiny Read Wrapper

Register demo:// with a stub class that returns fixed text.

PHP
<?php
class DemoStream {
    public $context;
    private $data = 'hello-demo';
    private $pos = 0;

    public function stream_open($path, $mode, $options, &$opened_path) {
        return true;
    }
    public function stream_read($count) {
        $chunk = substr($this->data, $this->pos, $count);
        $this->pos += strlen($chunk);
        return $chunk;
    }
    public function stream_eof() {
        return $this->pos >= strlen($this->data);
    }
    public function stream_stat() {
        return [];
    }
}

stream_wrapper_register('demo', DemoStream::class);
echo file_get_contents('demo://item'), PHP_EOL;

How It Works

  1. DemoStream implements the minimum read methods.
  2. stream_wrapper_register() adds the demo scheme.
  3. file_get_contents('demo://item') uses the class.
  4. The stub always returns hello-demo.

Example 2 — Registration Returns a Boolean

Print whether the protocol registered successfully.

PHP
<?php
class FlagStream {
    public $context;
    public function stream_open($path, $mode, $options, &$opened_path) { return true; }
    public function stream_read($count) { return ''; }
    public function stream_eof() { return true; }
    public function stream_stat() { return []; }
}

$ok = stream_wrapper_register('flag', FlagStream::class);
echo $ok ? 'registered' : 'failed', PHP_EOL;

How It Works

  1. Define a minimal stub class first.
  2. stream_wrapper_register() returns true on success.
  3. false usually means the name is taken or the class is invalid.
  4. Check stream_get_wrappers() to see active schemes.

Example 3 — List Wrappers After Register

Register a scheme and confirm it appears in stream_get_wrappers().

PHP
<?php
class ListStream {
    public $context;
    public function stream_open($path, $mode, $options, &$opened_path) { return true; }
    public function stream_read($count) { return ''; }
    public function stream_eof() { return true; }
    public function stream_stat() { return []; }
}

stream_wrapper_register('listme', ListStream::class);
echo in_array('listme', stream_get_wrappers(), true) ? 'listme present' : 'missing', PHP_EOL;

How It Works

  1. Register the listme protocol.
  2. stream_get_wrappers() returns all known schemes.
  3. in_array() confirms listme is present.
  4. Unregister later if the scheme was only temporary.

Frequently Asked Questions

It registers a custom protocol scheme so fopen() and friends can open URLs handled by your class.
It is an alias of stream_wrapper_register(). Both names do the same job.
Stream wrapper methods such as stream_open(), stream_read(), stream_eof(), and others depending on the features you need.
The protocol may already exist, or the class name may be invalid.
Call stream_wrapper_unregister() for that protocol name.

Next: stream_wrapper_restore()

stream_wrapper_restore() restores a previously unregistered built-in protocol wrapper.

stream_wrapper_restore() 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