sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 08:58:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fixes and clarifications to include() & require() behaviour wrt

Browse source 
variable scoping/passing.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@30541 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Torben Wilson 2000-08-19 22:07:27 +00:00
parent 7662ec553a
commit a922b1125d
1 changed files with 82 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
language/control-structures.xml
View file

@ -789,6 +789,13 @@ endswitch;
the specified file, much like the C preprocessor's
<literal>#include</literal> works.
</simpara>
<simpara>
If "URL fopen wrappers" are enabled in PHP (which they are in the
default configuration), you can specify the file to be
<function>require</function>ed using an URL instead of a local
pathname. See <link linkend="features.remote-files">Remote
files</link> and <function>fopen</function> for more information.
</simpara>
<simpara>
An important note about how this works is that when a file is
<function>include</function>ed or <function>require</function>ed,
@ -835,29 +842,49 @@ require ('header.inc');
</programlisting>
</informalexample>
</para>
<simpara>
When a file is <function>require</function>ed, the code it
contains inherits the variable scope of the line on which the
<function>require</function> occurs. Any variables available at
that line in the calling file will be available within the called
file. If the <function>require</function> 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.
</simpara>
<para>
Please note that both <function>include</function> and
<function>require</function> actually pull the contents of the
target file into the calling script file itself; they do not call
the target via HTTP or anything like that. So any variable set in
the scope in which the inclusion happens will be available within
the included file automatically, since it has effectively become a
part of the calling file.
If the <function>require</function>ed file is called via HTTP
using the fopen wrappers, and if the target server interprets the
target file as PHP code, variables may be passed to the
<function>require</function>ed file using an URL request string as
used with HTTP GET. This is not strictly speaking the same thing
as <function>require</function>ing 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.
<informalexample>
<programlisting role="php">
require ("file.inc?varone=1&amp;vartwo=2"); /* Won't work. */
/* This example assumes that someserver is configured to parse .php
* files and not .txt files. Also, 'works' here means that the variables
* $varone and $vartwo are available within the require()ed file. */
/* Won't work; file.txt wasn't handled by someserver. */
require ("http://someserver/file.txt?varone=1&amp;vartwo=2");
/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2'
* on the local filesystem. */
require ("file.php?varone=1&amp;vartwo=2");
/* Works. */
require ("http://someserver/file.php?varone=1&amp;vartwo=2");
$varone = 1;
$vartwo = 2;
require ("file.inc"); /* $varone and $vartwo will be available in file.inc */
require ("file.txt"); /* Works. */
require ("file.php"); /* Works. */
</programlisting>
</informalexample>
</para>
<simpara>
Don't be misled by the fact that you can require or include files
via HTTP using the <link linkend="features.remote-files">Remote
files</link> feature; the above holds true regardless.
</simpara>
<simpara>
In PHP3, it is possible to execute a <literal>return</literal>
statement inside a <function>require</function>ed file, as long as
@ -880,6 +907,13 @@ require ("file.inc"); /* $varone and $vartwo will be available in file.inc */
The <function>include</function> statement includes and evaluates
the specified file.
</simpara>
<simpara>
If "URL fopen wrappers" are enabled in PHP (which they are in the
default configuration), you can specify the file to be
<function>include</function>ed using an URL instead of a local
pathname. See <link linkend="features.remote-files">Remote
files</link> and <function>fopen</function> for more information.
</simpara>
<simpara>
An important note about how this works is that when a file is
<function>include</function>ed or <function>require</function>ed,
@ -1028,29 +1062,49 @@ Before the return
<literal>return</literal>ing values from files like that.
</para>
</example>
<simpara>
When a file is <function>include</function>ed, the code it
contains inherits the variable scope of the line on which the
<function>include</function> occurs. Any variables available at
that line in the calling file will be available within the called
file. If the <function>include</function> 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.
</simpara>
<para>
Please note that both <function>include</function> and
<function>require</function> actually pull the contents of the
target file into the calling script file itself; they do not call
the target via HTTP or anything like that. So any variable set in
the scope in which the inclusion happens will be available within
the included file automatically, since it has effectively become a
part of the calling file.
If the <function>include</function>ed file is called via HTTP
using the fopen wrappers, and if the target server interprets the
target file as PHP code, variables may be passed to the
<function>include</function>ed file using an URL request string as
used with HTTP GET. This is not strictly speaking the same thing
as <function>include</function>ing 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.
<informalexample>
<programlisting role="php">
include ("file.inc?varone=1&amp;vartwo=2"); /* Won't work. */
/* This example assumes that someserver is configured to parse .php
* files and not .txt files. Also, 'works' here means that the variables
* $varone and $vartwo are available within the include()ed file. */
/* Won't work; file.txt wasn't handled by someserver. */
include ("http://someserver/file.txt?varone=1&amp;vartwo=2");
/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2'
* on the local filesystem. */
include ("file.php?varone=1&amp;vartwo=2");
/* Works. */
include ("http://someserver/file.php?varone=1&amp;vartwo=2");
$varone = 1;
$vartwo = 2;
include ("file.inc"); /* $varone and $vartwo will be available in file.inc */
include ("file.txt"); /* Works. */
include ("file.php"); /* Works. */
</programlisting>
</informalexample>
</para>
<simpara>
Don't be misled by the fact that you can require or include files
via HTTP using the <link linkend="features.remote-files">Remote
files</link> feature; the above holds true regardless.
</simpara>
<simpara>
See also <function>require</function>, <function>require_once</function>,
<function>include_once</function>, <function>readfile</function>,