PHP. Руководство по PHP. 2005

include

Пред.

Глава 16. Control Structures

След.

include()

The include() statement includes and evaluates

the specified file.

The documentation below also applies to require().

The two constructs are identical in every way except how they handle

failure. include() produces a

Warning while require()

results in a Fatal Error.

In other words, use require() if you want

a missing file to halt processing of the page. include() does

not behave this way, the script will continue regardless. Be sure to have an

appropriate include_path setting as well.

Be warned that parse error in included file doesn't cause processing halting

in PHP versions prior to PHP4.3.5. Since this version, it does.

Files for including are first looked in include_path relative to the current working directory

and then in include_path relative to the directory of current script. E.g. if your include_path

is ., current working directory is /www/,

you included include/a.php and there is include "b.php"

in that file, b.php is first looked in /www/

and then in /www/include/.

If filename begins with ../, it is looked only in

include_path relative to the current working directory.

When a file is included, the code it contains inherits the

variable scope 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.

Пример 16-5. Basic include() example


vars.php
<?
$color = 'green';
$fruit = 'apple';
?>
test.php
<?
echo "A $color $fruit"; //A
include 'vars.php';
echo "A $color $fruit"; //A green apple

?>

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.

Пример 16-6. Including within functions


<?
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

?>

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

valid PHP start

and end tags.

If "URL fopen wrappers"

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 Прил. M 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.

Внимание

-Версии PHP для Windows до PHP4.3.0 не

поддерживают возможность использования удаленных файлов этой

функцией даже в том случае, если опция

allow_url_fopen

включена.

Пример 16-7. include() through HTTP


<?
/*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://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://example.com/file.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'file.txt'; //Works.
include 'file.php'; //Works.

?>

See also Remote files,

fopen() and file() for related

information.

Because include() and require()

are special language constructs, you must enclose them within a statement

block if it's inside a conditional block.

Пример 16-8. include() and conditional blocks


<?
//This is WRONG and will not work as desired.
if ($condition)
include $file;
else
include $other;
//This is CORRECT.
if ($condition){
include $file;
}else{
include $other;
}

?>

Handling Returns: It is possible to execute a return()

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

valid PHP start

and end tags (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.

Because include() is a special language construct,

parentheses are not needed around its argument. Take care when comparing

return value.

Пример 16-9. Comparing return value of include


<?
//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';
}

?>

Замечание:

In PHP 3, the return may not appear inside a block unless it's

a function block, in which case the return() applies

to that function and not the whole file.

Пример 16-10. include() and the return() statement


return.php
<?
$var = 'PHP';
return $var;
?>
noreturn.php
<?
$var = 'PHP';
?>
testreturns.php
<?
$foo = include 'return.php';
echo $foo; //prints 'PHP'
$bar = include 'noreturn.php';
echo $bar; //prints 1

?>

$bar is the value 1 because the include

was successful. Notice the difference between the above examples. The first uses

return() within the included file while the other does not.

If the file can't be included, FALSE is returned and

E_WARNING is issued.

If there are functions defined in the included file, they can be used in the

main file independent if they are before return() or after.

If the file is included twice, PHP5 issues fatal error because functions

were already declared, while PHP4 doesn't complain about functions

defined after return().

It is recommended to use include_once() instead of

checking if the file was already included and conditionally return inside

the included file.

Another way to "include" a PHP file into a variable is to capture the

output by using the Output Control

Functions with include(). For example:

Пример 16-11. Using output buffering to include a PHP file into a string


<?
$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;
}

?>

In order to automatically include files within scripts, see also the

auto_prepend_file and

auto_append_file

configuration options in php.ini.

Замечание: Поскольку это языковая

конструкция, а не функция, она не может вызываться при помощи

переменных функций

Ваше письмо	×