php-doc-en/language/control-structures/include.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->

<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title><function>include</function></title>
 <simpara>
  The <function>include</function> statement includes and evaluates
  the specified file.
 </simpara>
 <simpara>
  The documentation below also applies to <function>require</function>.
  The two constructs are identical in every way except how they handle
  failure. They both produce a
  <link linkend="errorfunc.constants.errorlevels.e-warning">Warning</link>, but <function>require</function>
  results in a <link linkend="errorfunc.constants.errorlevels.e-error">Fatal Error</link>.
  In other words, use <function>require</function> if you want
  a missing file to halt processing of the page.  <function>include</function> does
  not behave this way, the script will continue regardless.  Be sure to have an
  appropriate <link linkend="ini.include-path">include_path</link> setting as well.
  Be warned that parse error in included file doesn't cause processing halting
  in PHP versions prior to PHP 4.3.5. Since this version, it does.
 </simpara>
 <simpara>
  Files for including are first looked for in each include_path entry
  relative to the current working directory, and then in the directory of
  current script.
  E.g. if your include_path
  is <literal>libraries</literal>, current working directory is <filename class="directory">/www/</filename>,
  you included <filename>include/a.php</filename> and there is <literal>include "b.php"</literal>
  in that file, <filename>b.php</filename> is first looked in <filename class="directory">/www/libraries/</filename>
  and then in <filename class="directory">/www/include/</filename>.
  If filename begins with <literal>./</literal> or <literal>../</literal>, it
  is looked for only in the current working directory or parent of the
  current working directory, respectively.
 </simpara>
 <simpara>
  When a file is included, the code it contains inherits the
  <link linkend="language.variables.scope">variable scope</link> of the
  line on which the include occurs.  Any variables available at that line
  in the calling file will be available within the called file, from that
  point forward.
  However, all functions and classes defined in the included file have the
  global scope.
 </simpara>
 <para>
  <example>
   <title>Basic <function>include</function> example</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>
  If the include occurs inside a function within the calling file,
  then all of the code contained in the called file will behave as
  though it had been defined inside that function.  So, it will follow
  the variable scope of that function.
  An exception to this rule are <link
  linkend="language.constants.predefined">magic constants</link> which are
  evaluated by the parser before the include occurs.
 </simpara>
 <para>
  <example>
   <title>Including within functions</title>
   <programlisting role="php">
<![CDATA[
<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
* $fruit is NOT available outside of this  *
* scope.  $color is because we declared it *
* as global.                               */

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

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  When a file is included, parsing drops out of PHP mode and
  into HTML mode at the beginning of the target file, and resumes
  again at the end.  For this reason, any code inside the target
  file which should be executed as PHP code must be enclosed within
  <link linkend="language.basic-syntax.phpmode">valid PHP start
  and end tags</link>.
 </simpara>
 <simpara>
  If "<link linkend="ini.allow-url-fopen">URL fopen wrappers</link>"
  are enabled in PHP (which they are in the default configuration),
  you can specify the file to be included using a URL (via HTTP or
  other supported wrapper - see <xref linkend="wrappers"/> for a list
  of protocols) instead of a local pathname.  If the target server interprets
  the target file as PHP code, variables may be passed to the included
  file using a URL request string as used with HTTP GET.  This is
  not strictly speaking the same thing as including the file and having
  it inherit the parent file's variable scope; the script is actually
  being run on the remote server and the result is then being
  included into the local script.
 </simpara>
 &warn.no-win32-fopen-wrapper;
 <para>
  <example>
   <title><function>include</function> through HTTP</title>
   <programlisting role="php">
<![CDATA[
<?php

/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>Security warning</title>
  <para>
   Remote file may be processed at the remote server (depending on the file
   extension and the fact if the remote server runs PHP or not) but it still
   has to produce a valid PHP script because it will be processed at the
   local server. If the file from the remote server should be processed
   there and outputted only, <function>readfile</function> is much better
   function to use. Otherwise, special care should be taken to secure the
   remote script to produce a valid and desired code.
  </para>
 </warning>
 <para>
  See also <link linkend="features.remote-files">Remote files</link>,
  <function>fopen</function> and <function>file</function> for related
  information.
 </para>
 <simpara>
  Handling Returns: It is possible to execute a <function>return</function>
  statement inside an included file in order to terminate processing in that
  file and return to the script which called it.  Also, it's possible to return
  values from included files.  You can take the value of the include call as
  you would a normal function.  This is not, however, possible when including
  remote files unless the output of the remote file has
  <link linkend="language.basic-syntax.phpmode">valid PHP start
  and end tags</link> (as with any local file).  You can declare the needed
  variables within those tags and they will be introduced at whichever point
  the file was included.
 </simpara>
 <para>
  Because <function>include</function> is a special language construct,
  parentheses are not needed around its argument. Take care when comparing
  return value.
  <example>
   <title>Comparing return value of include</title>
   <programlisting role="php">
<![CDATA[
<?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';
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title><function>include</function> and the <function>return</function> statement</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; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  <literal>$bar</literal> is the value <literal>1</literal> because the include
  was successful.  Notice the difference between the above examples.  The first uses
  <function>return</function> within the included file while the other does not.
  If the file can't be included, &false; is returned and
  <literal>E_WARNING</literal> is issued.
 </simpara>
 <para>
  If there are functions defined in the included file, they can be used in the
  main file independent if they are before <function>return</function> or after.
  If the file is included twice, PHP 5 issues fatal error because functions
  were already declared, while PHP 4 doesn't complain about functions
  defined after <function>return</function>.
  It is recommended to use <function>include_once</function> instead of
  checking if the file was already included and conditionally return inside
  the included file.
 </para>
 <simpara>
  Another way to "include" a PHP file into a variable is to capture the
  output by using the <link linkend="ref.outcontrol">Output Control
  Functions</link> with <function>include</function>. For example:
 </simpara>
 <para>
  <example>
   <title>Using output buffering to include a PHP file into a string</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;
        $contents = ob_get_contents();
        ob_end_clean();
        return $contents;
    }
    return false;
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  In order to automatically include files within scripts, see also the
  <link linkend="ini.auto-prepend-file">auto_prepend_file</link> and
  <link linkend="ini.auto-append-file">auto_append_file</link>
  configuration options in &php.ini;.
 </para>

 &note.language-construct;

 <simpara>
  See also <function>require</function>, <function>require_once</function>,
  <function>include_once</function>, <function>get_included_files</function>,
  <function>readfile</function>, <function>virtual</function>, and
  <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:"../../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
-->