導入

ストリームは、PHP 4.3.0 に、 ファイル、ネットワーク、データ圧縮などに関する、 共通した一連の関数群と利用法を持つ操作の一般化の手法として 導入されました。もっとも単純な定義では、ストリーム というのは、ストリーミング可能な動作を体現する resource オブジェクトといえます。つまり、ストリームには線的に読み出したり、 あるいは書き込んだりすることが可能で、かつ、 ストリーム上の任意の場所に fseek() できる場合も あります。

ラッパー というのは、ストリームにおいてどのように特定の プロトコル/エンコーディングを扱うかを扱うかを指示する付加的なコード です。たとえば、http ラッパーは、どのようにして URL を、リモートサーバのファイルに対する HTTP/1.0 リクエストに転換するかを知っています。PHP には、デフォルトで組み込まれているラッパーが多数存在しますが (付録M を参照ください)、 それに加え、カスタムラッパーをstream_wrapper_register() を利用して PHP スクリプトの内部から、あるいはストリーム API を用いて、 直接拡張モジュールの内部から追加できます。 (ストリーム API については 第44章 を参照ください) あらゆる種類のラッパーが PHP に追加できるので、 特にラッパーでできることの限界はありません。 現在登録されているラッパーの種類を知るには、 stream_get_wrappers() を使います。

リソースは次のような形でストリームとして参照されます: scheme://target

• scheme(string) - 使用されるラッパの名称です。例として、 file, http, https, ftp, ftps, compress.zlib, compress.bz2, php などが含まれます。 PHP 組み込みのラッパについては、付録M を参照ください。もしラッパが指定されていない場合は、使用している関数の デフォルトが利用されます(通常は file://)。

• target - 使用するラッパによって解釈が異なります。 ファイルシステムに関連したストリームの場合、 一般的にこのパラメータは対象となるファイルの ファイル名とパスを表します。 ネットワークに関連したストリームの場合、一般的に このパラメータはホスト名と、(多くの場合付加されるはずの) パス名です。 PHP 組み込みのラッパに、どのようにターゲットが解釈されるかは、 付録M を参照ください。

ストリームフィルタ

フィルタ は、ストリームから読み込まれたり、 あるいは、ストリームから書き込まれたするデータに対して何らかの 操作を行う、最終段階にあるコードです。 PHP スクリプトの内部で、 stream_filter_register() を使って、 あるいは拡張モジュールの内部で 第44章 に示された 関連する API を使って、カスタムフィルタを作成することができます。 現在登録されているフィルタの一覧を取得するには、 stream_get_filters() をお使いください。

ストリームコンテキスト

コンテキスト は、ストリームの挙動を変えたり、 拡張したりすることのできる パラメータ と ラッパ固有の オプション の集合です。 コンテキスト は、 stream_context_create() を使って生成しますが、 これは、ほとんどのファイルシステム関連のストリーム生成関数に 渡すことができます。(例えば fopen(), file(), file_get_contents() など)

オプション は、 stream_context_create() の呼び出し時に指定しますが、 後で stream_context_set_option() を使って 指定することもできます。 ラッパ固有の オプション については、 組み込みラッパの一覧に説明があります。 (付録M を参照ください)

さらに、stream_context_set_params() を使うことで、 パラメータ を、コンテキスト に対し指定することができます。なお、現在のところ、PHP にサポートされているコンテキストパラメータ は、 notification のみです。このパラメータの値は、 ストリームに発生した何らかのイベントを通知するために呼び出される関数の 名前でなくてはなりません。 通知関数は次のような 6 個のパラメータを取ります:

void my_notifier ( int notification_code, int severity, string message, int message_code, int bytes_transferred, int bytes_max )

notification_code と severity は、下記の STREAM_NOTIFY_* 定数に該当する数値です。 もし、通知内容についての詳細メッセージがある場合、 message と message_code に適切な値が入ります。なお、これらの値の意味するところは使われている ラッパによって異なります。 bytes_transferred と bytes_max には、場合に応じて値が埋められます。

インストール手順

ストリームは、バージョン 4.3.0 より、PHP の一部として 統合されています。有効にするために特別な手順を踏む必要はありません。

ストリームのクラス

ユーザ定義のラッパは、stream_wrapper_register() で、同関数の説明ページに記載されたクラス定義を使うことで、 登録することができます。

ユーザ定義のフィルタ用に、class php_user_filter が、 ベースとなる抽象クラスとしてあらかじめ定義されています。 ユーザ定義のフィルタの実装に関する詳細は、 stream_filter_register() を参照ください。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ストリームのエラー

ファイルやソケット関連の関数で処理に失敗するのと同じように、 ストリームにおける操作も様々な予測できる理由で失敗することがあります。 (例: リモートホストに接続できない、ファイルが見つからない、等) また、ストリーム関連の関数呼び出しは、 スクリプトの実行されるシステムにおいて、 利用しようとしているストリームが登録されていないことから失敗することも あります。どのタイプのストリームがインストールされた PHP でサポートされているかは、 stream_get_wrappers() の返す配列の内容を参照 してください。なお、他の PHP の内部関数と同様、 E_WARNING メッセージがエラー時に出力され、 エラーの原因を報告します。

例

例 1. file_get_contents() を使って さまざまな場所からデータを取得する <?php /* /home/bar にあるローカルファイルを読み出す */ $localfile = file_get_contents("/home/bar/foo.txt"); /* 上と同一だが、明示的に FILE スキームを指定している */ $localfile = file_get_contents("file:///home/bar/foo.txt"); /* HTTP を利用し、www.example.com にあるリモートのファイルを読み出す */ $httpfile  = file_get_contents("http://www.example.com/foo.txt"); /* HTTPS を利用し、www.example.com にあるリモートのファイルを読み出す */ $httpsfile = file_get_contents("https://www.example.com/foo.txt"); /* FTP を利用し、ftp.example.com にあるリモートのファイルを読み出す */ $ftpfile   = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt"); /* FTPS を利用し、ftp.example.com にあるリモートのファイルを読み出す */ $ftpsfile  = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt"); ?>

例 2. https のサーバに対して POST リクエストを行う <?php /* https://secure.example.com/form_action.php に対して POST リクエストを送信 * ダミー値を持つ "foo" と "bar" というフォーム要素が含まれます。 */ $sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30); if (!$sock) die("$errstr ($errno)\n"); $data = "foo=" . urlencode("Fooの値") . "&bar=" . urlencode("Barの値"); fwrite($sock, "POST /form_action.php HTTP/1.0\r\n"); fwrite($sock, "Host: secure.example.com\r\n"); fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n"); fwrite($sock, "Content-length: " . strlen($data) . "\r\n"); fwrite($sock, "Accept: */*\r\n"); fwrite($sock, "\r\n"); fwrite($sock, "$data\r\n"); fwrite($sock, "\r\n"); $headers = ""; while ($str = trim(fgets($sock, 4096)))   $headers .= "$str\n"; echo "\n"; $body = ""; while (!feof($sock))   $body .= fgets($sock, 4096); fclose($sock); ?>

例 3. データを圧縮ファイルに書き込む <?php /* 任意の文字列を含む圧縮ファイルを作成 * ファイルは、compress.zlib ストリームを使っても、または単に * コマンドラインで 'gzip -d foo-bar.txt.gz' を使っても読み出せます。 */ $fp = fopen("compress.zlib://foo-bar.txt.gz", "wb"); if (!$fp) die("ファイルが作成できませぬ."); fwrite($fp, "これはテストです.\n"); fclose($fp); ?>