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

<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>
  The <literal>include</literal> expression includes and evaluates
  the specified file.
 </simpara>
 <simpara>
  The documentation below also applies to <function>require</function>.
 </simpara>
 <simpara>
  Files are included based on the file path given or, if none is given, the
  <link linkend="ini.include-path">include_path</link> specified. If the file
  isn't found in the <link linkend="ini.include-path">include_path</link>,
  <literal>include</literal> will finally check in the calling script's own
  directory and the current working directory before failing. The
  <literal>include</literal> construct will emit an
  <constant>E_WARNING</constant> if
  it cannot find a file; this is different behavior from
  <function>require</function>, which will emit an
  <constant>E_ERROR</constant>.
 </simpara>
 <simpara>
  Note that both <literal>include</literal> and <literal>require</literal>
  raise additional <constant>E_WARNING</constant>s, if the file cannot be
  accessed, before raising the final <constant>E_WARNING</constant> or
  <constant>E_ERROR</constant>, respectively.
 </simpara>
 <simpara>
  If a path is defined — whether absolute (starting with a drive letter
  or <literal>\</literal> on Windows, or <literal>/</literal> on Unix/Linux
  systems) or relative to the current directory (starting with
  <literal>.</literal> or <literal>..</literal>) — the
  <link linkend="ini.include-path">include_path</link> will be ignored
  altogether.  For example, if a filename begins with <literal>../</literal>,
  the parser will look in the parent directory to find the requested file.
 </simpara>
 <simpara>
  For more information on how PHP handles including files and the include path,
  see the documentation for <link linkend="ini.include-path">include_path</link>.
 </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 <literal>include</literal> 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-include">URL include wrappers</link>"
  are enabled in PHP,
  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>
 <para>
  <example>
   <title><literal>include</literal> 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';
?>
]]>
   </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: <literal>include</literal> returns
  <literal>FALSE</literal> on failure and raises a warning. Successful
  includes, unless overridden by the included file, return
  <literal>1</literal>. 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 for 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 <literal>include</literal> 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') == TRUE), i.e. include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// works
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title><literal>include</literal> 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
  <constant>E_WARNING</constant> 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 will raise a fatal error because the
  functions were already declared.
  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 <literal>include</literal>. 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;
        return ob_get_clean();
    }
    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:"~/.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
-->