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

stream_get_meta_data関数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年10月04日

基本的な使い方

stream_get_meta_data関数は、指定されたストリームのメタデータを取得する関数です。PHPにおけるストリームとは、ファイルやネットワーク接続など、連続するデータの流れを扱うための抽象的な仕組みを指します。この関数は、現在開かれているストリームの様々な属性や状態に関する情報を取得するために利用されます。

引数には、fopen()関数やfsockopen()関数などで開かれた有効なストリームリソースを渡します。例えば、開かれたファイルの読み書きモードや、ネットワークソケットのタイムアウト設定など、ストリームに関する詳細な情報を知りたい場合に役立ちます。

この関数は、ストリームのメタデータを含む連想配列を返します。この配列には、ストリームが読み込みモードか書き込みモードかを示すmode、パスのエイリアスを示すuri、バッファリングの状態を示すunread_bytes、ブロックモードかどうかを示すblocked、タイムアウト設定を示すtimed_out、ソケットの型を示すstream_typeといった要素が含まれることがあります。これらの情報は、ストリームを安全かつ効率的に操作するために重要です。例えば、ファイルの終端に達したかどうかを確認したり、ネットワーク通信のタイムアウトを検出したりする際に、このメタデータを利用することができます。

構文(syntax)


1<?php
2$stream = fopen('php://temp', 'r+');
3$metaData = stream_get_meta_data($stream);
4fclose($stream);

引数(parameters)

resource $stream

resource $stream: メタデータを取得したいストリームリソース

戻り値(return)

array

ストリームに関するメタデータ（プロトコル名、ホスト名、ポート番号、パス、フラグ、オプションなど）を連想配列形式で返します。

サンプルコード

PHP stream_get_meta_data でストリーム情報を取得する


1<?php
2
3/**
4 * ファイルストリームのメタデータを取得して表示するサンプル関数
5 *
6 * stream_get_meta_data() は、指定されたストリームリソースに関する
7 * 詳細な情報（メタデータ）を連想配列として返します。
8 * これにより、ストリームの状態やプロパティをプログラムで確認できます。
9 */
10function displayFileStreamMetaData(): void
11{
12    // 一時ファイルを作成し、そのパスを取得します。
13    // このファイルはスクリプト終了時に自動的に削除されませんが、後で手動で削除します。
14    $filePath = tempnam(sys_get_temp_dir(), 'meta_');
15
16    // ファイルを読み書きモード ('w+') で開きます。
17    // これにより、ファイルポインタを表す「ストリームリソース」が返されます。
18    $stream = fopen($filePath, 'w+');
19
20    if ($stream === false) {
21        echo "ファイルのオープンに失敗しました。" . PHP_EOL;
22        return;
23    }
24
25    try {
26        // ストリームにデータを書き込みます。
27        fwrite($stream, "Hello, PHP Stream!");
28
29        // stream_get_meta_data() を呼び出して、ストリームのメタデータを取得します。
30        $metaData = stream_get_meta_data($stream);
31
32        // 取得したメタデータを整形して表示します。
33        // 'uri', 'mode', 'stream_type' などが含まれていることがわかります。
34        echo "--- ストリームのメタデータ ---" . PHP_EOL;
35        print_r($metaData);
36        echo "--------------------------" . PHP_EOL;
37
38    } finally {
39        // 例外が発生した場合でも、必ずストリームを閉じ、ファイルを削除します。
40        fclose($stream);
41        unlink($filePath);
42    }
43}
44
45// 関数を実行して結果を確認します。
46displayFileStreamMetaData();
47
48?>

stream_get_meta_data関数は、ファイルやネットワーク接続といった「ストリーム」に関する詳細な情報（メタデータ）を取得するための関数です。

この関数の引数には、fopen関数などで開いたストリームリソースを指定します。ストリームリソースとは、プログラムがファイルなどを操作するための識別情報と考えるとよいでしょう。

関数が成功すると、戻り値としてストリームに関する様々な情報が格納された連想配列が返されます。この配列には、ストリームのタイムアウト設定、ブロックモードの状態、ファイルのパスを示す uri、開いた際のモードを示す mode、ストリームの種類を示す stream_type などが含まれています。

サンプルコードでは、まずfopenでファイルを開き、その操作の窓口となるストリームリソースを取得しています。次に、このリソースをstream_get_meta_data関数に渡すことでメタデータを取得し、画面に表示しています。この関数を利用することで、プログラムの実行中にストリームがどのような状態にあるかを動的に把握でき、デバッグや処理の分岐に役立ちます。

fopenで開いたストリームリソースは、処理が完了したら必ずfcloseで閉じる必要があります。サンプルコードで使われているtry...finally構文は、処理の途中でエラーが発生した場合でも、fcloseなどの後処理を確実に実行するための推奨される書き方です。また、fopenは失敗するとfalseを返すため、返り値が有効なリソースであるかを必ず確認してから使用してください。stream_get_meta_data関数が返す配列のキーや値は、ファイルやネットワークソケットといったストリームの種類によって内容が異なります。この関数はストリームの状態を確認するだけで、内容を変更することはありません。