PHP マニュアル
前のページ 第 16章制御構造 次のページ

include()

include() 文は指定されたファイルを読み込み、評価します。

以下の記述内容は require() にも当てはまります。これら2つの構文は、 エラーの扱い方を除けば全く同様に振舞います。エラーが発生するとどちらも Warning を出力しますが、 require() を使用している場合は Fatal Error となります。 言い換えると、指定されたファイルが無い場合に処理を停止したい場合は require() を使用した方が良い、ということになります。 include() を使用すると、読み込むべきファイルが存在しない 場合も処理が続行されます。 include_path を適切に設定することも忘れないでください。 PHP 4.3.5 より前のバージョンでは include されたファイルにパースエラーが あっても処理が続行されましたが、それ以降のバージョンでは処理を停止します。

読み込むファイルはまずカレントのワーキングディレクトリからの相対パスとしてinclude_path で探され、それから、カレントのスクリプトのディレクトリからの相対パスとしてinclude_path で探されます。 例えば、include_pathが . で、カレントの ワーキングディレクトリが /www/ の 場合、 include/a.php を読み込んで、そのファイルの中に include "b.php" と書いてあったとすると、 b.php がまず /www/ で探され、その後、 /www/include/ で探されます。 ファイル名が ./ あるいは ../ で始まっている場合は、 カレントのワーキングディレクトリからの相対パスとしてinclude_path で探されるのみとなります。

ファイルが読み込まれるとそのファイルに含まれるコードは、 include() もしくは require() が実行された 行の 変数スコープ を継承します。 呼び出し側の行で利用可能である全ての変数は、読み込まれたファイル内で利用可能です。 しかし、読み込まれたファイル内で定義されている関数やクラスはすべて グローバルスコープとなります。

例 16-5. 基本的な include() の例

vars.php
<?php

$color = 'green' ;
 $fruit = 'apple' ;

 ?>
test.php
<?php

 echo "A $color $fruit" ; // A

 include 'vars.php' ;

echo "A $color $fruit" ; // A green apple

 ?>

呼び出し側のファイルの関数定義の中で読み込みが行われ場合は、読み込まれる ファイルに含まれる全てのコードは、その関数内で定義されているものとして 動作します。従って変数スコープのその関数のものが継承されます。

例 16-6. 関数内での読み込み

<?php

 function foo ()
{
global $color ;

    include 'vars.php' ;

    echo "A $color $fruit" ;
}

 /* vars.php は foo() のスコープを継承するため *
* $fruit はこの関数の外では無効となります。  *
* $color はglobalとして宣言されているため    *
* 有効です。                                 */

 foo ();                     // A green apple
 echo "A $color $fruit" ;    // A green

 ?>

ファイルが読み込まれるときには、読み込まれるファイルの先頭で PHPモードを抜けてHTMLモードになり、最後に再びPHPモードに戻ります。 このため、読み込むファイル中のPHPコードとして実行する必要がある コードは、 有効なPHPの開始タグおよび終了タグ で括る必要があります。

" URL fopenラッパー "が 有効になっている場合(デフォルト設定では有効です)、ローカルなパス名 の代わりにURL(HTTP経由)を用いて読み込むファイルを指定することが可能です。 URLで指定されたサーバがファイルをPHPコードとして解釈することが 出来る場合には、HTTP GETを使用してURLリクエストに引数を指定することが 出来ます。これはファイルの読み込み云々やスコープの継承とは関係なく、 ただ単純にスクリプトがリモートのサーバで実行されて結果がローカルの スクリプトに読み込まれる、というだけのことです。

警告

PHP 4.3.0 より前のバージョンの Windows 版 PHP は、現在この関数に関してリモートファイルアクセス機能を サポートしていません。これは、 allow_url_fopen を 有効にした場合でも同様です。

例 16-7. HTTP経由の include()

<?php

 /* この例は www.example.com が.phpはPHPスクリプトとして扱い、.txtは通常の *
* ファイルとして扱うように設定されていると仮定しています。また、ここでの *
* '動作します'という言葉の意味は、変数$fooと$barが読み込まれる側のファイ *
* ルで使用可能である、ということです。                                   */

// 動作しません: www.example.com では file.txt はPHPコードとして解釈されません。
 include 'http://www.example.com/file.txt?foo=1&bar=2' ;

 // 動作しません: 'file.php?foo=1&bar=2' という名前のファイルをローカルファイル
// システム上から探し出そうとします。
 include 'file.php?foo=1&bar=2' ;

 // 動作します。
 include 'http://www.example.com/file.php?foo=1&bar=2' ;

 $foo = 1 ;
 $bar = 2 ;
include 'file.txt' ;   // 動作する
 include 'file.php' ;   // 動作する

 ?>

セキュリティの警告

リモートファイルはリモートサーバ上で実行されます（ファイルの拡張子や リモートサーバが PHP の実行を許可しているかどうかに依存します）が、 有効な PHP スクリプトである必要があります。なぜならそれはローカル サーバ上で処理されるからです。もしリモートサーバ上で処理された結果が ほしいだけならば、 readfile() を使用するほうがよい でしょう。そうでなければ、リモートスクリプトが有効な期待通りのコードを 生成していることを確認するため、注意を払うことが必要になります。

リモートファイル , fopen() , file() も参照してください。

値の返し方: 読み込まれたファイル内では、ファイルの実行処理を終了し呼出側の スクリプトに戻るために return() 文を実行することが可能です。 読み込まれたファイルから値を返すことも可能です。 通常の関数で行うのと同様にincludeコールの値を取得することができます。 しかし、読み込まれたリモートファイル(ローカルファイルの場合も同様)の出力が、 有効なPHPの開始／ 終了タグ を有していない限り、リモートファイルを読み込む際に値を 取得することはできません。 必要な変数をこれらのタグの中で宣言することができ、これらの変数は ファイルが読み込まれた位置で使用可能となります。

include() は特別な言語構造であるため、 引数の前後に括弧は不要です。 返り値を比較する際には注意してください。

例 16-8. インクルードの戻り値を比較する

<?php
 // won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
 if (include( 'vars.php' ) == 'OK' ) {
    echo 'OK' ;
}

 // works
 if ((include 'vars.php' ) == 'OK' ) {
    echo 'OK' ;
}
 ?>

注意: PHP 3では関数ブロック以外のブロック内でreturnを 使用することはできません。 return() が適用されるのは関数であり、ファイル全体ではありません。

例 16-9. include() と return() 文

return.php
<?php

$var = 'PHP' ;

return $var ;

 ?>
noreturn.php
<?php

$var = 'PHP' ;

 ?>
testreturns.php
<?php

$foo = include 'return.php' ;

echo $foo ; // 'PHP'と出力されます

 $bar = include 'noreturn.php' ;

echo $bar ; // 1が出力されます

 ?>

読み込みが成功すると $bar の値は1となります。上の2つの例の違いに 注目してください。最初の例では読み込まれるファイル側で return() を使用し、もう一方では使用していません。 ファイルが読み込めなかった場合、 FALSE が返され、 E_WARNING が発生します。

読み込まれるファイルで定義された関数がある場合、 これらは、 return() の前後によらず メインファイルで使用できます。 このファイルが二度読み込まれた場合、PHP 5は関数が定義済みであるため 致命的なエラーを発生します。一方、PHP 4は return() の後に定義された関数については、 エラーを発生しません。 ファイルが読み込み済みであるかどうかを調べ、 読み込まれるファイルの内容を条件分岐で返すかわりに include_once() を使用することを推奨します。

PHP ファイルの内容を変数に "include する" もうひとつの方法は、 出力制御関数 を include() とともに用いて 出力をキャプチャすることです。たとえば、

例 16-10. 出力バッファリングを用い、 PHP ファイルの内容を文字列として読み込む

<?php
$string = get_include_contents ( 'somefile.php' );

function get_include_contents ( $filename ) {
    if ( is_file ( $filename )) {
         ob_start ();
        include $filename ;
         $contents = ob_get_contents ();
         ob_end_clean ();
        return $contents ;
    }
    return false ;
}

 ?>

スクリプト中で自動的にファイルをインクルードするには、 php.ini の auto_prepend_file および auto_append_file オプションも参照ください。

注意: これは、関数ではなく 言語構造のため、 可変関数 を用いて コールすることはできません。

require() , require_once() , include_once() , get_included_files() , readfile() , virtual() および include_path も参照ください。

前のページ ホーム 次のページ
require() 上に戻る require_once()