(PHP 4, PHP 5, PHP 7, PHP 8)
include 式は指定されたファイルを読み込み、評価します。
以下の記述内容は require にも当てはまります。
ファイルのインクルードは、指定されたパスから行います。パスを指定しない場合は、
include_path の設定を利用します。
ファイルが include_path
に見つからないときは、include
は呼び出し元スクリプトのディレクトリと現在の作業ディレクトリも探します。
include は、ファイルを見つけられない場合に
E_WARNING
を発行します。一方 require の場合は、同じ場合に
E_ERROR
を発行する点が異なります。
include と require は、
ファイルがアクセスできない場合、
最終的に E_WARNING や E_ERROR を発生させる前に、
追加の E_WARNING を発生させることに注意して下さい。
パスを指定した場合 —
絶対パス (Windows ならドライブレターあるいは
\ で始まるパス、Unix/Linux 系なら /
で始まるパス) あるいはカレントディレクトリからの相対パス
(. あるいは .. で始まるパス) のどちらでも
— は
include_path は無視されます。たとえば
../ ではじまるファイル名を指定した場合は、
親ディレクトリからそのファイルを探します。
PHP でのファイルのインクルードやインクルードパスについての詳細は include_path のドキュメントを参照ください。
ファイルが読み込まれるとそのファイルに含まれるコードは、 includeもしくはrequireが実行された 行の変数スコープを継承します。 呼び出し側の行で利用可能である全ての変数は、読み込まれたファイル内で利用可能です。 しかし、読み込まれたファイル内で定義されている関数やクラスはすべて グローバルスコープとなります。
例1 基本的な 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
?>
呼び出し側のファイルの関数定義の中で読み込みが行われた場合は、 読み込まれるファイルに含まれる全てのコードは、 その関数内で定義されているものとして動作します。 従って変数のスコープもその関数のものが継承されます。 ただ マジック定数 は例外で、これは読み込みを行う前にパーサが評価します。
例2 関数内での読み込み
<?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 include ラッパー"が 有効になっている場合、ローカルなパス名 の代わりにURL(HTTP経由)を用いて読み込むファイルを指定することが可能です。 URLで指定されたサーバーがファイルをPHPコードとして解釈することが 出来る場合には、HTTP GETを使用してURLリクエストに引数を指定することが 出来ます。これはファイルの読み込み云々やスコープの継承とは関係なく、 ただ単純にスクリプトがリモートのサーバーで実行されて結果がローカルの スクリプトに読み込まれる、というだけのことです。
例3 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';
?>
リモートファイルはリモートサーバー上で実行されます（ファイルの拡張子や リモートサーバーが PHP の実行を許可しているかどうかに依存します）が、 有効な PHP スクリプトである必要があります。なぜならそれはローカル サーバー上で処理されるからです。もしリモートサーバー上で処理された結果が ほしいだけならば、readfile() を使用するほうがよい でしょう。そうでなければ、リモートスクリプトが有効な期待通りのコードを 生成していることを確認するため、注意を払うことが必要になります。
リモートファイル, fopen(), file()も参照してください。
値の返し方: include に失敗したときには
FALSE を返し、警告を発生させます。
成功した場合の戻り値は、インクルードしたファイル側で変更していない限りは
1 です。
インクルードしたファイルの中で return を実行すれば、
そのファイルの処理をそこで止めて呼び出し元に処理を戻せます。
読み込まれたファイルから値を返すことも可能です。
通常の関数で行うのと同様にincludeコールの値を取得することができます。
しかし、読み込まれたリモートファイル(ローカルファイルの場合も同様)の出力が、
有効なPHPの開始／
終了タグを有していない限り、リモートファイルを読み込む際に値を
取得することはできません。
必要な変数をこれらのタグの中で宣言することができ、これらの変数は
ファイルが読み込まれた位置で使用可能となります。
include は特別な言語構造であるため、
引数の前後に括弧は不要です。
戻り値を比較する際には注意してください。
例4 インクルードの戻り値を比較する
<?php
// 動作しません。include(('vars.php') == TRUE) つまり、include('1') と評価されます
if (include('vars.php') == TRUE) {
echo 'OK';
}
// 動作します。
if ((include 'vars.php') == TRUE) {
echo 'OK';
}
?>
例5 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 の前後によらず メインファイルで使用できます。 このファイルが二度読み込まれた場合、関数が定義済みであるため 致命的なエラーが発生します。 ファイルが読み込み済みであるかどうかを調べ、 読み込まれるファイルの内容を条件分岐で返すかわりに include_once を使用することを推奨します。
PHP ファイルの内容を変数に "include する" もうひとつの方法は、
出力制御関数
を include とともに用いて
出力をキャプチャすることです。たとえば、
例6 出力バッファリングを用い、 PHP ファイルの内容を文字列として読み込む
<?php
$string = get_include_contents('somefile.php');
function get_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include $filename;
return ob_get_clean();
}
return false;
}
?>
スクリプト中で自動的にファイルをインクルードするには、php.ini の auto_prepend_file および auto_append_file オプションも参照ください。
require, require_once, include_once, get_included_files(), readfile(), virtual() および include_path も参照ください。