【PHP8.x】stream_register_wrapper関数の使い方

<?php

declare(strict_types=1);

/**
 * グローバル変数をストリームとして読み込むためのカスタムラッパークラス
 *
 * このクラスは 'var://' というカスタムプロトコルを実装します。
 * 例えば、file_get_contents('var://my_variable') を実行すると、
 * グローバル変数 $my_variable の内容を文字列として読み込むことができます。
 */
class VariableStreamWrapper
{
    /** @var resource|null ストリームコンテキスト */
    public $context;

    /** @var string 読み込むデータの内容 */
    private string $data;

    /** @var int 現在の読み取り位置 */
    private int $position;

    /**
     * ストリームが開かれるときに呼び出されます。
     *
     * @param string $path アクセス先のパス (例: "var://my_variable")
     * @param string $mode アクセスモード (例: 'r', 'w')
     * @param int $options ストリームオープン時のオプション
     * @param ?string &$opened_path 実際に開かれたパスを格納するための参照
     * @return bool 成功した場合に true, 失敗した場合に false
     */
    public function stream_open(string $path, string $mode, int $options, ?string &$opened_path): bool
    {
        // URLからホスト部分（変数名）を取得します。
        $variableName = parse_url($path, PHP_URL_HOST);

        // 変数名が取得できない、またはグローバルスコープに存在しない場合は失敗とします。
        if ($variableName === null || !array_key_exists($variableName, $GLOBALS)) {
            return false;
        }

        // 読み込むデータをプロパティにセットします。
        $this->data = (string) $GLOBALS[$variableName];
        $this->position = 0;

        return true;
    }

    /**
     * ストリームからデータを読み込むときに呼び出されます。
     *
     * @param int $count 読み込む最大バイト数
     * @return string|false 読み込んだデータ、または終端なら空文字列、エラーなら false
     */
    public function stream_read(int $count): string|false
    {
        // 現在位置から指定バイト数のデータを切り出します。
        $chunk = substr($this->data, $this->position, $count);
        // 読み取り位置を進めます。
        $this->position += strlen($chunk);
        return $chunk;
    }

    /**
     * ストリームの終端に達したかどうかを判定します。
     *
     * @return bool 終端に達した場合は true
     */
    public function stream_eof(): bool
    {
        return $this->position >= strlen($this->data);
    }

    /**
     * ストリームのメタ情報（ファイルサイズなど）を取得します。
     * fstat() 関数の呼び出しに対応します。
     *
     * @return array|false メタ情報の配列、または false
     */
    public function stream_stat(): array|false
    {
        return ['size' => strlen($this->data)];
    }

    /**
     * パスのメタ情報を取得します。
     * file_exists() や filesize() などの呼び出しに対応します。
     *
     * @param string $path アクセス先のパス
     * @param int $flags STREAM_URL_STAT_LINK または STREAM_URL_STAT_QUIET
     * @return array|false メタ情報の配列、または false
     */
    public function url_stat(string $path, int $flags): array|false
    {
        $variableName = parse_url($path, PHP_URL_HOST);
        if ($variableName !== null && array_key_exists($variableName, $GLOBALS)) {
            return ['size' => strlen((string)$GLOBALS[$variableName])];
        }
        return false;
    }
}

// --- これより下が実行部分 ---

// ラッパーが読み込むためのグローバル変数を定義
$message = "Hello, custom stream wrapper!";
$user_id = 12345;

// 'var' プロトコルに対して VariableStreamWrapper クラスを登録します。
// これにより、'var://' で始まるパスがこのクラスで処理されるようになります。
stream_wrapper_register('var', VariableStreamWrapper::class);

echo "--- 'var://message' の読み込み ---\n";
// file_get_contents でカスタムプロトコルを使用して変数の内容を読み込む
$content = file_get_contents('var://message');
echo $content . "\n\n";

echo "--- 'var://user_id' の読み込み ---\n";
$content = file_get_contents('var://user_id');
echo $content . "\n\n";

echo "--- file_exists() による存在確認 ---\n";
// 存在する変数
var_dump(file_exists('var://message'));
// 存在しない変数
var_dump(file_exists('var://undefined_variable'));

// 後片付けとして、登録したラッパーを解除します。
stream_wrapper_unregister('var');

?>

stream_wrapper_register関数は、PHPに独自のURLプロトコルを追加するための機能です。これにより、http://やfile://のように、自分で定義したプロトコルをfile_get_contents()などのファイル操作関数で扱えるようになります。

この関数の第1引数$protocolには、登録したいプロトコル名（サンプルでは'var'）を文字列で指定します。第2引数$classnameには、そのプロトコルの処理を担当するクラス名（サンプルではVariableStreamWrapper::class）を指定します。関数は、プロトコルの登録に成功するとtrueを、失敗するとfalseを返します。

サンプルコードでは、stream_wrapper_registerによって'var'プロトコルとVariableStreamWrapperクラスを紐づけています。この登録以降、file_get_contents('var://message')のようなコードが実行されると、PHPはファイルシステムにアクセスする代わりにVariableStreamWrapperクラスのメソッドを呼び出します。その結果、ファイルを読むのと同じ操作で、グローバル変数$messageの内容を取得できています。このように、様々なデータソースをファイルと同じように統一的な方法で扱う仕組みを実装できます。