svn: /phpdoc/en/trunk/ appendices/ini.xml language/control-structures/include.xml

brandon Wed, 12 Aug 2009 11:53:57 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=287153 Log: Updating include and include_path documentation to be more clear and explicit. Changed paths: U phpdoc/en/trunk/appendices/ini.xml U phpdoc/en/trunk/language/control-structures/include.xml Modified: phpdoc/en/trunk/appendices/ini.xml =================================================================== --- phpdoc/en/trunk/appendices/ini.xml 2009-08-12 11:07:15 UTC (rev 287152) +++ phpdoc/en/trunk/appendices/ini.xml 2009-08-12 11:53:57 UTC (rev 287153) @@ -4639,6 +4639,16 @@ separated with a colon in Unix or semicolon in Windows. </para> <para> + PHP considers each entry in the include path separately when looking for + files to include. It will check the first path, and if it doesn't find + it, check the next path, until it either locates the included file or + returns with a + <link linkend="errorfunc.constants.errorlevels.e-warning">warning</link> + or an <link linkend="errorfunc.constants.errorlevels.e-error">error</link>. + You may modify or set your include path at runtime using + <function>set_include_path</function>. + </para> + <para> <example> <title>Unix include_path</title> <programlisting role="php.ini"> Modified: phpdoc/en/trunk/language/control-structures/include.xml =================================================================== --- phpdoc/en/trunk/language/control-structures/include.xml 2009-08-12 11:07:15 UTC (rev 287152) +++ phpdoc/en/trunk/language/control-structures/include.xml 2009-08-12 11:53:57 UTC (rev 287153) @@ -9,31 +9,27 @@ </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. + Files are included based on the file path given or, if none is given, the + <link linkend="ini.include-path">include_path</link> specified. The + <function>include</function> construct will emit a + <link linkend="errorfunc.constants.errorlevels.e-warning">warning</link> if it + cannot find a file; this is different behavior from <function>require</a>, + which will emit a + <link linkend="errorfunc.constants.errorlevels.e-error">fatal error</link>. </simpara> <simpara> + If a path is defined (full or relative), 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