fopen()はfilenameで指定された リソースをストリームに結び付けます。 filenameが "スキーム://..." の形式である場合、 それはURLとみなされ、PHPはそのプロトコルのハンドラ (ラッパとしても知られる)を探します。 もしもそのプロトコルに対するラッパが登録されていない場合、 PHPはスクリプトに潜在的な問題があることを示すNOTICEを発行したうえで、 filenameを通常のファイルとみなして オープンすることを試みます。
PHPは、filenameがローカルのファイルを示していると みなすと、そのファイルへのストリームをオープンします。 そのファイルはPHPからアクセスできるものでなければなりません。 ファイルのパーミッションが(パラメータで指定された)アクセスを 許可されているかどうか確認する必要があります。 セーフモード またはopen_basedirを 有効にしている場合は更なるアクセス制限が加えられることがあります。
filenameが登録されているプロトコルを 示しているとPHPが判断し、かつそのプロトコルがネットワークURLとして 登録されていれば、PHPはallow_url_fopen が有効となっているかどうかチェックします。 もしこれがオフになっていると、PHPはwarningを発行しfopenは失敗します。
注意: サポートされているプロトコルのリストは付録Mにあります。 いくつかのプロトコル(wrappersにも関連する)は context かつ/または php.ini のオプションをサポートします。 使用するプロトコルについてセットされるオプションのリストについては それぞれのページを見てください (例えば、 php.ini 上の user_agentの値は httpラッパが使用します)。
注意: コンテキストのサポートは、 PHP 5.0.0 で追加されました。contexts の説明に関しては、 参照CL, ストリーム関数 を参照してください。
注意: PHP4.3.2以降では、バイナリモードとテキストモードを区別する全ての プラットフォームにおいて、デフォルトのモードはバイナリにセットされます。 アップグレード後にスクリプトに問題が起きた場合は、 以上に述べたスクリプトの互換性を確保するまでの次善策として、 't'フラグを試してみてください。
パラメータmode は、そのストリームに要する アクセス形式を指定します。この指定は、下表のうちのどれかとなります。
表 1. fopen()で使用可能な modeのリスト
mode | 説明 |
---|---|
'r' | 読み込みのみでオープンします。ファイルポインタをファイルの 先頭に置きます。 |
'r+' | 読み込み/書き出し用にオープンします。ファイルポインタを ファイルの先頭に置きます。 |
'w' | 書き出しのみでオープンします。ファイルポインタをファイルの 先頭に置き、ファイルサイズをゼロにします。ファイルが存在しない 場合には、作成を試みます。 |
'w+' | 読み込み/書き出し用でオープンします。ファイルポインタを ファイルの先頭に置き、ファイルサイズをゼロにします。 ファイルが存在しない場合には、作成を試みます。 |
'a' | 書き出し用のみでオープンします。ファイルポインタをファイルの 終端に置きます。ファイルが存在しない場合には、作成を試みます。 |
'a+' | 読み込み/書き出し用でオープンします。ファイルポインタを ファイルの終端に置きます。ファイルが存在しない場合には、作成を 試みます。 |
'x' | 書き込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。 ファイルが既に存在する場合にはfopen()は失敗し、 E_WARNINGレベルのエラーを発行します。 ファイルが存在しない場合には新規作成を試みます。 これはopen(2)システムコールにおける O_EXCL|O_CREATフラグの指定と等価です。 このオプションはPHP4.3.2以降でサポートされ、また、 ローカルファイルに対してのみ有効です。 |
'x+' | 読み込み/書き出し用でオープンします。ファイルポインタをファイルの先頭に置きます。 ファイルが既に存在する場合にはfopen()は失敗し、 E_WARNINGレベルのエラーを発行します。 これはopen(2)システムコールにおける O_EXCL|O_CREATフラグの指定と等価です。 このオプションはPHP4.3.2以降でサポートされ、また、 ローカルファイルに対してのみ有効です。 |
注意: オペレーティングシステムファミリが異なると行末も異なります。 テキストファイルに書き出し、そこに改行を加えたいとき、 オペレーティングシステムにあわせた正しい改行コードを使用する必要があります。 UNIXベースのシステムでは改行に\nキャラクタを使用します。 Windowsベースのシステムでは\r\nを使用します。 マッキントッシュベースのシステムでは\rを使用します。
間違った改行コードでファイルに書き込むと、他のアプリケーション上でそのファイルを 開いた際に変な風に見えてしまいます。
Windows上では、\nを\r\nに透過的に変換する text-mode変換フラグ('t')が提供されます。 それに対し、'b'を使って強制的にバイナリモードにすることもできます。 その場合データの変換はされません。 このフラグを使用するには、'b' または 't'を mode引数の最後に追加してください。
デフォルトの変換モードはSAPIと使用しているPHPのバージョンによって異なります。 したがって、互換性の意味から、常に適切なフラグを指定することが推奨されます。 plain-textファイルを使用する場合には't'モードを指定すべきであり、 改行に\nを使用すると、 メモ帳のようなアプリケーションで読めることを期待できます。 それ以外のケースでは'b'を使うべきです。
バイナリファイルを扱っている際に 'b' フラグを指定しなかった場合、 画像ファイルが壊れたり、\r\n キャラクタがおかしくなる等の問題を抱えてしまうでしょう。
注意: 互換性維持のために、fopen()でファイルをオープンする際は 常に'b'フラグを指定することが強く推奨されます。
注意: 互換性維持のために、't'モードを使用または依存している コードを書き直し、正しい改行コードと'b'モードを代わりに 使用することが、強く推奨されます。
オプションの3番目の引数use_include_pathに'1'又は TRUE を設定することにより、include_path のファイルの検索も行うこともできます。
オープンが失敗すると、関数は FALSE を返し、 E_WARNING レベルのエラーを発行します。 @ を使ってこのwarningを抑制することもできます。
ファイルの読みこみ・書きこみ時に問題が発生し、 サーバーモジュール版のPHPを使用している場合、 使用するファイル・ディレクトリがサーバープロセスからアクセス可能 かどうかを確認してみてください。
Windows 環境では、ファイルパスで用いる全てのバックスラッシュを エスケープするかフォワードスラッシュを使用することに注意してください。
警告 |
IIS のような、いくつかの標準に 対応してない Web サーバは、PHP に警告を発生させるような手順でデータを送信します。 このようなサーバを使用する場合は、 error_reporting を警告を発生しないレベルまで小さくする必要があります。 PHP 4.3.7 以降では、https:// ラッパーでストリームをオープンする際に バグがある IIS サーバソフトウエアを検出することができ、この警告を抑制することができます。 あなたが ssl:// ソケットを作性するために fsockopen() を使用している場合、 自らこの警告を検出し、抑制する必要があります。 |
注意: セーフモード が有効の場合、PHP は、 操作を行うディレクトリが、実行するスクリプトと同じ UID (所有者)を有しているか どうかを確認します。
付録M, fclose(), fgets(), fread(), fwrite(), fsockopen(), file(), file_exists(), is_readable(), stream_set_timeout(), popen() も参照ください。