<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false" role="stream_wrapper">

<refnamediv>

<refname>php://</refname>

<refpurpose>さまざまな入出力ストリームへのアクセス</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<para>

PHP ではさまざまな入出力ストリームを提供しています。

これらを使うと、PHP 自身の入出力ストリームへのアクセスや

標準入出力と標準エラー出力のファイル記述子へのアクセス、

メモリやディスクを使ったテンポラリファイルストリームへのアクセスができ、

フィルタを使って他のファイルリソースの読み書きに手を加えることもできます。

</para>

<refsect2 xml:id="wrappers.php.std">

<title>php://stdin, php://stdout および php://stderr</title>

<simpara>

<filename>php://stdin</filename>、<filename>php://stdout</filename>

および <filename>php://stderr</filename> は、PHP プロセスの

対応する入出力ストリームへの直接アクセスを許可します。

これらのストリームは複製されたファイル記述子を参照します。そのため、

<filename>php://stdin</filename> をオープンしたあとでそれを閉じたとしても、

識別子のコピーが閉じられるだけです。<constant>STDIN</constant>

で参照される実際のストリームは何も影響を受けません。

これらのラッパーを使うのではなく、定数

<constant>STDIN</constant>, <constant>STDOUT</constant>

および <constant>STDERR</constant> を使用することを推奨します。

</simpara>

<simpara>

<filename>php://stdin</filename> は読み込み専用で、

<filename>php://stdout</filename> および <filename>php://stderr</filename>

は書き込み専用です。

</simpara>

</refsect2>

<refsect2 xml:id="wrappers.php.input">

<title>php://input</title>

<simpara>

<filename>php://input</filename> は読み込み専用のストリームで、

リクエストの body 部から生のデータを読み込むことができます。

<link linkend="ini.enable-post-data-reading">enable_post_data_reading</link> オプションが有効になっている場合、

かつ <literal>enctype="multipart/form-data"</literal> を指定した POST リクエストでは、<filename>php://input</filename> は使用できません。

</simpara>

</refsect2>

<refsect2 xml:id="wrappers.php.output">

<title>php://output</title>

<para>

<filename>php://output</filename> は書き込み専用のストリームで、

<function>print</function> および <function>echo</function>

と同じ方法での出力バッファへの書き込みを許可します。

</para>

</refsect2>

<refsect2 xml:id="wrappers.php.fd">

<title>php://fd</title>

<simpara>

<filename>php://fd</filename> は、指定したファイル記述子に直接アクセスすることができます。

たとえば <filename>php://fd/3</filename> は、ファイル記述子 3 を指します。

</simpara>

</refsect2>

<refsect2 xml:id="wrappers.php.memory">

<title>php://memory および php://temp</title>

<simpara>

<filename>php://memory</filename> および <filename>php://temp</filename>

は読み書き可能なストリームで、一時データをファイルのように保存できるラッパーです。

両者の違いは、

<filename>php://memory</filename> が常にデータをメモリに格納するのに対して

<filename>php://temp</filename> は定義済みの上限 (デフォルトは 2 MB)

に達するとテンポラリファイルを使うという点です。

このテンポラリファイルの場所は、

<function>sys_get_temp_dir</function> 関数と同じ方法で決めます。

</simpara>

<simpara>

<filename>php://temp</filename> のメモリ制限を制御するには

<literal>/maxmemory:NN</literal> を追加します。この <literal>NN</literal>

はメモリに保持するデータの最大量で、単位はバイトです。

このサイズを超えるとテンポラリファイルを使います。

</simpara>

<caution>

<simpara>

PHP の拡張モジュールによっては、

標準入出力が必須なものがあるかもしれません。

その場合、指定されたストリームを標準入出力のストリームにキャストしようとするかもしれませんが、メモリに格納するストリームの場合、このキャストは失敗する可能性があります。なぜなら、C言語の <function>fopencookie</function> 関数が使える必要があるからです。この関数は、Windows では <emphasis>利用できません</emphasis>。

</simpara>

</caution>

</refsect2>

<refsect2 xml:id="wrappers.php.filter">

<title>php://filter</title>

<simpara>

<filename>php://filter</filename> は、<link linkend="filters">フィルタ</link>アプリケーションが

ストリームをオープンすることを許可するために設計されたメタラッパーです。

これは、<function>readfile</function>、<function>file</function>

および <function>file_get_contents</function> のようなオールインワンの

ファイル関数とともに使用すると有用です。これらの関数には、コンテンツが

読み込まれる前にストリームにフィルタを適用する手段がありません。

</simpara>

<para>

<filename>php://filter</filename> の対象は、

次のようなパラメータをパスの一部として受け取ります。

ひとつのパスに対して複数のフィルタチェインを指定できます。

これらのパラメータの詳細は、使用例を参照ください。

</para>

<para>

<table>

<title>php://filter のパラメータ</title>

<tgroup cols="2">

<thead>

<row>

<entry>名前</entry>

<entry>説明</entry>

</row>

</thead>

<tbody>

<row>

<entry>

<literal>resource=&lt;フィルタの対象となるストリーム&gt;</literal>

</entry>

<entry>

このパラメータは必須です。フィルタリングしたいストリームを指定します。

</entry>

</row>

<row>

<entry>

<literal>read=&lt;読み込みチェーンに適用するフィルタのリスト&gt;</literal>

</entry>

<entry>

このパラメータは任意です。ひとつあるいは複数のフィルタ名を、

パイプ文字 (<literal>|</literal>) で区切って指定します。

</entry>

</row>

<row>

<entry>

<literal>write=&lt;書き込みチェーンに適用するフィルタのリスト&gt;</literal>

</entry>

<entry>

このパラメータは任意です。ひとつあるいは複数のフィルタ名を、

パイプ文字 (<literal>|</literal>) で区切って指定します。

</entry>

</row>

<row>

<entry>

<literal>&lt;両方のチェーンに適用するフィルタのリスト&gt;</literal>

</entry>

<entry>

<literal>read=</literal> や <literal>write=</literal>

がついていないすべてのフィルタは、読み込みと書き込みのチェーンの両方に適切に適用されます。

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

</refsect2>

</refsect1>

<refsect1 role="options"><!-- {{{ -->

&reftitle.options;

<para>

<table>

<title>

ラッパーの概要（<literal>php://filter</literal> については、

フィルタされる側のラッパーの概要を参照します）

</title>

<tgroup cols="2">

<thead>

<row>

<entry>属性</entry>

<entry>サポートの有無</entry>

</row>

</thead>

<tbody>

<row>

<entry><link linkend="ini.allow-url-fopen">allow_url_fopen</link> で制約される</entry>

<entry>No</entry>

</row>

<row>

<entry><link linkend="ini.allow-url-include">allow_url_include</link> で制約される</entry>

<entry>

<literal>php://input</literal>、

<literal>php://stdin</literal>、

<literal>php://memory</literal> および

<literal>php://temp</literal> のみ。

</entry>

</row>

<row>

<entry>読み込み許可</entry>

<entry>

<literal>php://stdin</literal>、

<literal>php://input</literal>、

<literal>php://fd</literal>、

<literal>php://memory</literal> および

<literal>php://temp</literal> のみ。

</entry>

</row>

<row>

<entry>書き込み許可</entry>

<entry>

<literal>php://stdout</literal>、

<literal>php://stderr</literal>、

<literal>php://output</literal>、

<literal>php://fd</literal>、

<literal>php://memory</literal> および

<literal>php://temp</literal> のみ。

</entry>

</row>

<row>

<entry>追加許可</entry>

<entry>

<literal>php://stdout</literal>、

<literal>php://stderr</literal>、

<literal>php://output</literal>、

<literal>php://fd</literal>、

<literal>php://memory</literal> および

<literal>php://temp</literal> のみ (書き込みと同じ)。

</entry>

</row>

<row>

<entry>同時読み書き許可</entry>

<entry>

<literal>php://fd</literal>、

<literal>php://memory</literal> および

<literal>php://temp</literal> のみ。

</entry>

</row>

<row>

<entry><function>stat</function> のサポート</entry>

<entry>

No.

但し、<literal>php://memory</literal> および

<literal>php://temp</literal> は、<function>fstat</function> をサポートしています。

</entry>

</row>

<row>

<entry><function>unlink</function> のサポート</entry>

<entry>No</entry>

</row>

<row>

<entry><function>rename</function> のサポート</entry>

<entry>No</entry>

</row>

<row>

<entry><function>mkdir</function> のサポート</entry>

<entry>No</entry>

</row>

<row>

<entry><function>rmdir</function> のサポート</entry>

<entry>No</entry>

</row>

<row>

<entry><function>stream_select</function> のサポート</entry>

<entry>

<literal>php://stdin</literal>、

<literal>php://stdout</literal>、

<literal>php://stderr</literal>、

<literal>php://fd</literal>、および

<literal>php://temp</literal> のみ。

</entry>

</row>

</tbody>

</tgroup>

</table>

</para>

</refsect1> <!-- }}} -->

<refsect1 role="examples"><!-- {{{ -->

&reftitle.examples;

<example><!-- {{{ -->

<title>php://temp/maxmemory</title>

<para>

このオプションパラメータは、<filename>php://temp</filename>

がテンポラリファイルを使うようになるまでのメモリの制限を設定します。

</para>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

<example><!-- {{{ -->

<title>php://filter/resource=&lt;フィルタの対象となるストリーム&gt;</title>

<para>

このパラメータは、

<filename>php://filter</filename> 指定の最後に存在し、フィルタリング

したいストリームを指している必要があります。

</para>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

<example><!-- {{{ -->

<title>php://filter/read=&lt;読み込みチェーンに適用するフィルタのリスト&gt;</title>

<para>

このパラメータは 1 つ以上のフィルタ名を

パラメータとしてとり、それらはパイプ文字 <literal>|</literal> で区切られます。

</para>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

<example><!-- {{{ -->

<title>php://filter/write=&lt;書き込みチェーンに適用するフィルタのリスト&gt;</title>

<para>

このパラメータは 1 つ以上のフィルタ名を

パラメータとしてとり、それらはパイプ文字 <literal>|</literal> で区切られます。

</para>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

<example>

<title>php://memory と php://temp は再利用できない</title>

<para>

<filename>php://memory</filename> と <filename>php://temp</filename>

の再利用はできません。つまり、いったんストリームを閉じてしまったら、もうそれを参照できないということです。

</para>

<programlisting role="php">

</programlisting>

</example>

<example>

<title>リクエストボディから、JSON データを読み取るために php://input を使う</title>

<para>

この例は、<filename>php://input</filename> を使って POST, PUT,

PATCH リクエスト経由で生の JSON データを読み取る方法を示します。

</para>

<programlisting role="php">

</programlisting>

</example>

</refsect1><!-- }}} -->

</refentry>