 |
 |
 |
 |
|
|
Date: 08/19/00
- Next message: Hartmut Holzgraefe ( <email protected>): "Re: [PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b"
- Previous message: Jesus M. Castagnetto: "[PHP-DOC] cvs: phpdoc /en/functions info.xml"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
torben Sat Aug 19 15:07:28 2000 EDT
Modified files:
/phpdoc/en/language control-structures.xml
Log:
Fixes and clarifications to include() & require() behaviour wrt
variable scoping/passing.
Index: phpdoc/en/language/control-structures.xml
diff -u phpdoc/en/language/control-structures.xml:1.17 phpdoc/en/language/control-structures.xml:1.18
--- phpdoc/en/language/control-structures.xml:1.17 Fri Aug 18 23:13:31 2000
+++ phpdoc/en/language/control-structures.xml Sat Aug 19 15:07:27 2000
@@ -790,6 +790,13 @@
<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,
parsing drops out of PHP mode and into HTML mode at the beginning
@@ -835,30 +842,50 @@
</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&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&vartwo=2");
+/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
+ * on the local filesystem. */
+require ("file.php?varone=1&vartwo=2");
+
+/* Works. */
+require ("http://someserver/file.php?varone=1&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
that statement occurs in the global scope of the
@@ -881,6 +908,13 @@
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,
parsing drops out of PHP mode and into HTML mode at the beginning
@@ -1028,29 +1062,49 @@
<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&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&vartwo=2");
+/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
+ * on the local filesystem. */
+include ("file.php?varone=1&vartwo=2");
+
+/* Works. */
+include ("http://someserver/file.php?varone=1&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>,
- Next message: Hartmut Holzgraefe ( <email protected>): "Re: [PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b"
- Previous message: Jesus M. Castagnetto: "[PHP-DOC] cvs: phpdoc /en/functions info.xml"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]