include.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ffbe6525350c91d58e1d5b7a52c46c911035c8e0 Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->

<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>include</title>
 <?phpdoc print-version-for="include"?>
 <simpara>
  <literal>include</literal> 式は指定されたファイルを読み込み、評価します。
 </simpara>
 <simpara>
  以下の記述内容は <function>require</function> にも当てはまります。
 </simpara>
 <simpara>
  ファイルのインクルードは、指定されたパスから行います。パスを指定しない場合は、
  <link linkend="ini.include-path">include_path</link> の設定を利用します。
  ファイルが <link linkend="ini.include-path">include_path</link>
  に見つからないときは、<literal>include</literal>
  は呼び出し元スクリプトのディレクトリと現在の作業ディレクトリも探します。
  <literal>include</literal> は、ファイルを見つけられない場合に
  <constant>E_WARNING</constant>
  を発行します。一方 <function>require</function> の場合は、同じ場合に
  <constant>E_ERROR</constant>
  を発行する点が異なります。
 </simpara>
 <simpara>
  <literal>include</literal> と <literal>require</literal> は、
  ファイルがアクセスできない場合、
  最終的に <constant>E_WARNING</constant> や <constant>E_ERROR</constant> を発生させる前に、
  追加の <constant>E_WARNING</constant> を発生させることに注意して下さい。
 </simpara>
 <simpara>
  パスを指定した場合 —
  絶対パス (Windows ならドライブレターあるいは
  <literal>\</literal> で始まるパス、Unix/Linux 系なら <literal>/</literal>
  で始まるパス) あるいはカレントディレクトリからの相対パス
  (<literal>.</literal> あるいは <literal>..</literal> で始まるパス) のどちらでも
  — は
  <link linkend="ini.include-path">include_path</link> は無視されます。たとえば
  <literal>../</literal> ではじまるファイル名を指定した場合は、
  親ディレクトリからそのファイルを探します。
 </simpara>
 <simpara>
  PHP でのファイルのインクルードやインクルードパスについての詳細は
  <link linkend="ini.include-path">include_path</link> のドキュメントを参照ください。
 </simpara>
 <simpara>
  ファイルが読み込まれるとそのファイルに含まれるコードは、
  <function>include</function>もしくは<function>require</function>が実行された
  行の<link linkend="language.variables.scope">変数スコープ</link>を継承します。
  呼び出し側の行で利用可能である全ての変数は、読み込まれたファイル内で利用可能です。
  しかし、読み込まれたファイル内で定義されている関数やクラスはすべて
  グローバルスコープとなります。
 </simpara>
 <para>
  <example>
   <title>基本的な <literal>include</literal> の例</title>
   <programlisting role="php">
<![CDATA[
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

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  呼び出し側のファイルの関数定義の中で読み込みが行われた場合は、
  読み込まれるファイルに含まれる全てのコードは、
  その関数内で定義されているものとして動作します。
  従って変数のスコープもその関数のものが継承されます。
  ただ <link
  linkend="language.constants.predefined">マジック定数</link>
  は例外で、これは読み込みを行う前にパーサが評価します。
 </simpara>
 <para>
  <example>
   <title>関数内での読み込み</title>
   <programlisting role="php">
<![CDATA[
<?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

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  ファイルが読み込まれるときには、読み込まれるファイルの先頭で
  PHPモードを抜けてHTMLモードになり、最後に再びPHPモードに戻ります。
  このため、読み込むファイル中のPHPコードとして実行する必要がある
  コードは、<link linkend="language.basic-syntax.phpmode">
  有効なPHPの開始タグおよび終了タグ</link>で括る必要があります。
 </simpara>
 <simpara>
  "<link linkend="ini.allow-url-include">URL include ラッパー</link>"が
  有効になっている場合、ローカルなパス名
  の代わりにURL(HTTP経由)を用いて読み込むファイルを指定することが可能です。
  URLで指定されたサーバーがファイルをPHPコードとして解釈することが
  出来る場合には、HTTP GETを使用してURLリクエストに引数を指定することが
  出来ます。これはファイルの読み込み云々やスコープの継承とは関係なく、
  ただ単純にスクリプトがリモートのサーバーで実行されて結果がローカルの
  スクリプトに読み込まれる、というだけのことです。
 </simpara>
 <para>
  <example>
   <title>HTTP経由の <literal>include</literal></title>
   <programlisting role="php">
<![CDATA[
<?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';
?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>セキュリティの警告</title>
  <para>
   リモートファイルはリモートサーバー上で実行されます（ファイルの拡張子や
   リモートサーバーが PHP の実行を許可しているかどうかに依存します）が、
   有効な PHP スクリプトである必要があります。なぜならそれはローカル
   サーバー上で処理されるからです。もしリモートサーバー上で処理された結果が
   ほしいだけならば、<function>readfile</function> を使用するほうがよい
   でしょう。そうでなければ、リモートスクリプトが有効な期待通りのコードを
   生成していることを確認するため、注意を払うことが必要になります。
  </para>
 </warning>
 <para>
  <link linkend="features.remote-files">リモートファイル</link>,
  <function>fopen</function>, <function>file</function>も参照ください。
 </para>
 <simpara>
  値の返し方: <literal>include</literal> に失敗したときには
  <literal>FALSE</literal> を返し、警告を発生させます。
  成功した場合の戻り値は、インクルードしたファイル側で変更していない限りは
  <literal>1</literal> です。
  インクルードしたファイルの中で <function>return</function> を実行すれば、
  そのファイルの処理をそこで止めて呼び出し元に処理を戻せます。
  読み込まれたファイルから値を返すことも可能です。
  通常の関数で行うのと同様にincludeコールの値を取得することができます。
  しかし、読み込まれたリモートファイル(ローカルファイルの場合も同様)の出力が、
  <link linkend="language.basic-syntax.phpmode">有効なPHPの開始／
   終了タグ</link>を有していない限り、リモートファイルを読み込む際に値を
  取得することはできません。
  必要な変数をこれらのタグの中で宣言することができ、これらの変数は
  ファイルが読み込まれた位置で使用可能となります。
 </simpara>
 <para>
  <literal>include</literal> は特別な言語構造であるため、
  引数の前後に括弧は不要です。
  戻り値を比較する際には注意してください。
  <example>
   <title>インクルードの戻り値を比較する</title>
   <programlisting role="php">
<![CDATA[
<?php
// 動作しません。include(('vars.php') == TRUE) つまり、include('1') と評価されます
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// 動作します。
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title><literal>include</literal> と <function>return</function> 文</title>
   <programlisting role="php">
<![CDATA[
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が出力されます

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  読み込みが成功すると<literal>$bar</literal>の値は1となります。上の2つの例の違いに
  注目してください。最初の例では読み込まれるファイル側で <function>return</function>
  を使用し、もう一方では使用していません。
  ファイルが読み込めなかった場合、&false; が返され、
  <constant>E_WARNING</constant> が発生します。
 </simpara>
 <para>
  読み込まれるファイルで定義された関数がある場合、
  これらは、<function>return</function> の前後によらず
  メインファイルで使用できます。
  このファイルが二度読み込まれた場合、関数が定義済みであるため
  致命的なエラーが発生します。
  ファイルが読み込み済みであるかどうかを調べ、
  読み込まれるファイルの内容を条件分岐で返すかわりに
  <function>include_once</function> を使用することを推奨します。
 </para>
 <simpara>
  PHP ファイルの内容を変数に "include する" もうひとつの方法は、
  <link linkend="ref.outcontrol">出力制御関数</link>
  を <literal>include</literal> とともに用いて
  出力をキャプチャすることです。たとえば、
 </simpara>
 <para>
  <example>
   <title>出力バッファリングを用い、 PHP ファイルの内容を文字列として読み込む</title>
   <programlisting role="php">
<![CDATA[
<?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;
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  スクリプト中で自動的にファイルをインクルードするには、&php.ini; の
  <link linkend="ini.auto-prepend-file">auto_prepend_file</link> および
  <link linkend="ini.auto-append-file">auto_append_file</link>
  オプションも参照ください。
 </para>

 &note.language-construct;

 <simpara>
  <function>require</function>, <function>require_once</function>,
  <function>include_once</function>, <function>get_included_files</function>,
  <function>readfile</function>, <function>virtual</function> および
  <link linkend="ini.include-path">include_path</link> も参照ください。
 </simpara>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->