PHP stream_register_wrapper() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_register_wrapper() registers a custom stream wrapper class under a protocol name so fopen() and related functions can open URLs like myproto://path.

It is an alias of stream_wrapper_register(): same parameters, same behavior. Prefer stream_wrapper_register() in new code, but you may still meet stream_register_wrapper() in older examples.

Syntax

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

PHP
$ok = stream_register_wrapper("demo", DemoStream::class);
CallWhat it does
stream_register_wrapper("demo", "DemoStream")Registers DemoStream for demo:// URLs.
stream_wrapper_register("demo", "DemoStream")Same call using the primary function name.
stream_register_wrapper("file", "DemoStream")Fails if the protocol is already registered, unless you restore/unregister first.

Your class must implement the stream wrapper methods PHP expects (at least stream_open plus the read/write methods you need). After a successful register, the protocol appears in stream_get_wrappers().

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

Parameters

ParameterDescription
protocolRequired. The wrapper name used before :// in URLs.
classRequired. The class name that implements the wrapper.
flagsOptional. 0 by default, or STREAM_IS_URL to mark the wrapper as a URL wrapper.

Return Value

Return ValueDescription
booltrue on successful registration; false on failure.

PHP Examples

Example 1 — Register a Tiny Read Wrapper

Register a simple wrapper, open it, read fixed text, then unregister.

PHP
<?php
class TinyWrap {
    public $context;
    private $data = "hello";
    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_register_wrapper("tiny", TinyWrap::class);
$fp = fopen("tiny://x", "r");
echo stream_get_contents($fp), PHP_EOL;
fclose($fp);
stream_wrapper_unregister("tiny");

How It Works

  1. TinyWrap implements the minimum methods for a readable wrapper.
  2. stream_register_wrapper() links the protocol tiny to that class.
  3. fopen("tiny://x") creates an instance and stream_get_contents() reads hello.
  4. stream_wrapper_unregister() removes the custom protocol afterward.

Example 2 — See the Protocol in stream_get_wrappers()

Register a wrapper and confirm its name appears in the wrapper list.

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

stream_register_wrapper("listme", ListWrap::class);
echo in_array("listme", stream_get_wrappers(), true) ? "listed" : "missing", PHP_EOL;
stream_wrapper_unregister("listme");

How It Works

  1. A minimal wrapper class is defined.
  2. stream_register_wrapper() registers the listme protocol.
  3. stream_get_wrappers() now includes listme.
  4. Unregister cleans up so later demos stay isolated.

Example 3 — Alias Matches stream_wrapper_register()

Show that the alias and the primary name both report success for a fresh protocol.

PHP
<?php
class AliasWrap {
    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 []; }
}

$a = stream_register_wrapper("aliasdemo", AliasWrap::class);
stream_wrapper_unregister("aliasdemo");
$b = stream_wrapper_register("aliasdemo", AliasWrap::class);
stream_wrapper_unregister("aliasdemo");

echo $a && $b ? "same behavior" : "different", PHP_EOL;

How It Works

  1. We register once with stream_register_wrapper() and once with stream_wrapper_register().
  2. Each call returns true for a free protocol name.
  3. Unregister runs between attempts so the second register can succeed.
  4. Printing same behavior emphasizes that the names are aliases.

Frequently Asked Questions

It registers a user stream wrapper class under a protocol name so PHP can open that protocol with fopen() and friends.
No. stream_register_wrapper() is an alias of stream_wrapper_register(). They share the same behavior.
At least the stream methods you need, commonly stream_open, stream_read or stream_write, stream_eof, and stream_stat. Add more methods for seek, lock, or directory support.
Usually the protocol is already taken, or the class name is invalid. Unregister or restore the existing wrapper, then try again.
Prefer stream_wrapper_register(). Keep stream_register_wrapper() in mind when reading older tutorials.

Next: stream_resolve_include_path()

stream_resolve_include_path() searches the include_path for a relative filename and return.

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