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

<?php

/**
 * 'var://' プロトコルを処理するためのカスタムストリームラッパークラス
 *
 * このラッパーは、グローバル変数をファイルのように読み書きできるようにします。
 * 例:
 * - file_get_contents('var://my_variable') : $my_variable の値を読み取る
 * - file_put_contents('var://my_variable', 'new value') : $my_variable に値を書き込む
 */
class VariableStreamWrapper
{
    /** @var resource|null コンテキストリソース */
    public $context;

    /** @var int 現在の読み取り/書き込み位置 */
    private int $position = 0;

    /** @var string 変数の内容を保持するバッファ */
    private string $content = '';

    /** @var string アクセス対象の変数名 */
    private string $variableName;

    /**
     * ストリームを開く際に呼び出される
     *
     * @param string $path アクセス先のパス (例: 'var://my_variable')
     * @param string $mode アクセスモード (例: 'r', 'w')
     * @param int $options オプションフラグ
     * @param string|null $opened_path 実際に開いたパスを格納する変数
     * @return bool 成功した場合に true
     */
    public function stream_open(string $path, string $mode, int $options, ?string &$opened_path): bool
    {
        // URLからホスト部分（=変数名）を取得
        $url = parse_url($path);
        if (!isset($url['host']) || empty($url['host'])) {
            return false;
        }
        $this->variableName = $url['host'];

        // 読み取りモードの場合、グローバル変数から内容を読み込む
        // 変数が存在しない場合は空文字列として扱う
        if (str_contains($mode, 'r') || str_contains($mode, '+')) {
            $this->content = (string)($GLOBALS[$this->variableName] ?? '');
        }

        $this->position = 0;
        return true;
    }

    /**
     * ストリームからデータを読み取る際に呼び出される
     *
     * @param int $count 読み取る最大バイト数
     * @return string|false 読み取ったデータ、終端で空文字列、エラー時に false
     */
    public function stream_read(int $count): string|false
    {
        $data = substr($this->content, $this->position, $count);
        $this->position += strlen($data);
        return $data;
    }

    /**
     * ストリームにデータを書き込む際に呼び出される
     *
     * @param string $data 書き込むデータ
     * @return int 書き込んだバイト数
     */
    public function stream_write(string $data): int
    {
        // バッファの内容を新しいデータで上書きする (wモードの単純な実装)
        $this->content = substr_replace($this->content, $data, $this->position);
        $this->position += strlen($data);
        return strlen($data);
    }

    /**
     * ストリームを閉じる際に呼び出される
     * 書き込みモードで開かれていた場合、バッファの内容をグローバル変数に反映させる
     */
    public function stream_close(): void
    {
        $GLOBALS[$this->variableName] = $this->content;
    }

    /**
     * ストリームの終端に達したかどうかを判定する際に呼び出される
     *
     * @return bool 終端に達していれば true
     */
    public function stream_eof(): bool
    {
        return $this->position >= strlen($this->content);
    }

    /**
     * ファイルの情報を取得する際に呼び出される (例: file_exists())
     *
     * @param string $path ファイルパス
     * @param int $flags フラグ
     * @return array|false ファイル情報の配列、または失敗時に false
     */
    public function url_stat(string $path, int $flags): array|false
    {
        $url = parse_url($path);
        if (!isset($url['host']) || !array_key_exists($url['host'], $GLOBALS)) {
            // 変数が存在しない場合は false を返す
            return false;
        }

        // stat() 関数の戻り値に似た形式で、基本的な情報を返す
        $content = (string)$GLOBALS[$url['host']];
        return [
            'size' => strlen($content),
            'mode' => 0100644, // 通常のファイル、読み書き可能
            'mtime' => time(),
            'atime' => time(),
            'ctime' => time(),
        ];
    }
}

// --- ここからが実行サンプル ---

// 操作対象のグローバル変数を定義
$myAppData = 'Initial Value';

// 作成したラッパークラスを 'var' というプロトコル名で登録する
// これにより 'var://' で始まるパスが VariableStreamWrapper で処理されるようになる
stream_wrapper_register('var', VariableStreamWrapper::class);

echo "--- 操作前の状態 ---" . PHP_EOL;
echo '$myAppData の値: ' . $myAppData . PHP_EOL;
echo PHP_EOL;

// 'var://' プロトコルを使って、ファイルのようにグローバル変数に書き込む
echo "--- file_put_contents('var://myAppData', ...) を実行 ---" . PHP_EOL;
file_put_contents('var://myAppData', 'Hello from Custom Stream Wrapper!');
echo '$myAppData の値: ' . $myAppData . PHP_EOL;
echo PHP_EOL;

// 'var://' プロトコルを使って、ファイルのようにグローバル変数から読み込む
echo "--- file_get_contents('var://myAppData') を実行 ---" . PHP_EOL;
$content = file_get_contents('var://myAppData');
echo '読み込んだ値: ' . $content . PHP_EOL;
echo PHP_EOL;

// file_exists() で変数の存在を確認する
echo "--- file_exists() で存在確認 ---" . PHP_EOL;
echo "file_exists('var://myAppData'): " . (file_exists('var://myAppData') ? 'true' : 'false') . PHP_EOL;
echo "file_exists('var://nonExistentVar'): " . (file_exists('var://nonExistentVar') ? 'true' : 'false') . PHP_EOL;

// 登録したラッパーを解除（必須ではないが、後片付けとして推奨される）
stream_wrapper_unregister('var');

?>

stream_wrapper_register関数は、ユーザーが独自に定義したプロトコルをPHPに登録し、ファイル操作関数で利用できるようにするための関数です。これにより、例えばデータベースやAPI、変数などを、あたかもファイルであるかのように扱うことが可能になります。

第1引数$protocolには、登録したいプロトコル名を文字列で指定します。サンプルコードでは'var'がこれにあたり、以降var://で始まるパスが特別に処理されます。第2引数$classには、そのプロトコルの具体的な振る舞いを実装したクラス名を指定します。このクラスには、ファイルの読み書きなどの処理をメソッドとして定義しておく必要があります。第3引数$flagsは、ラッパーの動作を調整するオプションですが、通常は省略可能です。

この関数は、登録が成功した場合はtrueを、失敗した場合はfalseを返します。

サンプルコードでは、'var'というプロトコルをVariableStreamWrapperクラスに結びつけています。この登録によって、file_put_contents('var://myAppData', ...)のような一般的なファイル書き込み関数が、実際にはグローバル変数$myAppDataの値を更新する、という独自の動作を実現しています。