fopen()はfilenameで指定された リソースをストリームに結び付けます。 filenameが "スキーム://..." の形式である場合、 それはURLとみなされ、PHPはそのプロトコルのハンドラ (ラッパとしても知られる)を探します。 もしもそのプロトコルに対するラッパが登録されていない場合、 PHPはスクリプトに潜在的な問題があることを示すNOTICEを発行したうえで、 filenameを通常のファイルとみなして オープンすることを試みます。
PHPは、filenameがローカルのファイルを示していると みなすと、そのファイルへのストリームをオープンします。 そのファイルはPHPからアクセスできるものでなければなりません。 ファイルのパーミッションが(パラメータで指定された)アクセスを 許可されているかどうか確認する必要があります。 セーフモード またはopen_basedirを 有効にしている場合は更なるアクセス制限が加えられることがあります。
filenameが登録されているプロトコルを 示しているとPHPが判断し、かつそのプロトコルがネットワークURLとして 登録されていれば、PHPはallow_url_fopen が有効となっているかどうかチェックします。 もしこれがオフになっていると、PHPはwarningを発行しfopenは失敗します。
注意: サポートされているプロトコルのリストは付録Jにあります。 いくつかのプロトコル(wrappersにも関連する)は context かつ/または php.ini のオプションをサポートします。 使用するプロトコルについてセットされるオプションのリストについては それぞれのページを見てください。(例えば、 php.ini 上の user_agentの値はhttpラッパが使用します) contextsとzcontext引数についての 詳細は参照CVI, ストリーム関数をご覧ください。
The mode parameter specifies the type of access you require to the stream. It may be any of the following: 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'モードを代わりに 使用することが、強く推奨されます。
PHP4.3.2以降では、バイナリモードとテキストモードを区別する全ての プラットフォームにおいて、デフォルトのモードはバイナリにセットされます。 アップグレード後にスクリプトに問題が起きた場合は、 以上に述べたスクリプトの互換性を確保するまでの次善策として、 't'フラグを試してみてください。
オプションの3番目の引数use_include_pathに'1'又は TRUE を設定することにより、include_path のファイルの検索も行うこともできます。
If the open fails, the function returns FALSE and an error of level E_WARNING is generated. You may use @ to suppress this warning. オープンが失敗すると、関数は FALSE を返し、E_WARNING レベルのエラーを発行します。@ を使ってこのwarningを抑制することもできます。
ファイルの読みこみ・書きこみ時に問題が発生し、 サーバーモジュール版のPHPを使用している場合、 使用するファイル・ディレクトリがサーバープロセスからアクセス可能 かどうかを確認してみてください。
Windows 環境では、ファイルパスで用いる全てのバックスラッシュを エスケープするかフォワードスラッシュを使用することに注意して下さい。
付録J, fclose(), fgets(), fread(), fwrite(), fsockopen(), file(), file_exists(), is_readable(), stream_set_timeout(), popen() も参照下さい。