(PHP 4, PHP 5, PHP 7, PHP 8)
Выражение include включает и выполняет файл.
Документация ниже также относится к выражению require.
Файлы включаются исходя из пути указанного файла, или, если путь не указали,
PHP ищет файлы по путям, которые определили в директиве
include_path. Если файл
не найден в include_path,
выражение include попытается проверить директорию,
в которой находится текущий включающий скрипт,
и текущую рабочую директорию, перед тем как выдать ошибку. Конструкция
include выдаст ошибку уровня E_WARNING,
если не сможет найти файл; поведение отличается от выражения require,
которое выдаст фатальную ошибку E_ERROR.
Обратите внимание, что и выражение include,
и выражение require
выдают дополнительную ошибку уровня E_WARNING,
если к файлу невозможно получить доступ до выдачи последней ошибки уровня
E_WARNING или E_ERROR, соответственно.
Если путь указали — абсолютный (который начинается с буквы диска или с
обратного слеша \ в Windows или с прямого слеша /
в системах Unix или Linux) или относительно текущей директории (начинающийся с
. или ..) —
выражение include_path вообще будет проигнорировано.
Например, если имя файла начинается с ../,
парсер будет искать запрошенный файл в родительской директории.
Документация к директиве include_path подробнее рассказывает об обработке языком PHP включаемых файлов и путей.
Когда файл включается, код файл наследует ту же область видимости переменных, что и строка, на которой произошло включение. Переменные, которые доступны на этой строке во включающем файле, будут также доступны во включаемом файле. Однако у функций и классов, которые объявили во включаемом файле, будет глобальная область видимости.
Пример #1 Простой пример include
vars.php
<?php
$color = 'зелёное';
$fruit = 'яблоко';
?>
test.php
<?php
echo "Одно $color $fruit"; // Одно
include 'vars.php';
echo "Одно $color $fruit"; // Одно зелёное яблоко
?>Если файл включается внутри функции включающего файла, тогда код, который содержится во включаемом файле, будет вести себя так, как будто он его определили внутри этой функции. То есть, код будет в той же области видимости переменных этой функции. Исключение к этому правилу — магические константы, которые выполняются парсером перед включением.
Пример #2 Включение внутри функции
<?php
function foo()
{
global $color;
include 'vars.php';
echo "Одно $color $fruit";
}
/**
* Файл vars.php в той же области видимости, что и функция foo(),
* поэтому переменная $fruit НЕ будет доступна за пределами этой области.
* Переменная $color — доступна, поскольку её объявили глобальной
*/
foo(); // Одно зелёное яблоко
echo "Одно $color $fruit"; // Одно зелёное
?>Когда файл включается, парсинг в режиме PHP-кода прекращается и переключается в режим HTML в начале указанного файла и продолжается снова в конце. Поэтому любой код внутри включаемого файла, который должен быть выполнен как код PHP, должен быть заключён в корректные теги начала и конца PHP-кода.
Если "обёртки URL include" включены в PHP, допускается также указать файл для включения через URL (через HTTP или других поддерживающихся обработчиков — смотрите Поддерживаемые протоколы и обёртки для списка протоколов) вместо локального пути. Если целевой сервер интерпретирует указанный файл как PHP-код, переменные можно передать во включаемый файл через строку URL-запроса HTTP-методом GET. Это не то же самое, что включение файла и наследование родительской области видимости; скрипт выполняется на удалённом сервере, а результат затем включается в локальный скрипт.
Пример #3 Пример include через HTTP
<?php
/**
* В этом примере предполагается, что адрес www.example.com настроен на обработку
* файлов .php, но не .txt. Также, «Сработает» здесь означает, что переменные
* $foo и $bar доступны внутри включаемого файла.
*/
// Не сработает; файл file.txt не обрабатывается адресом www.example.com как PHP-код
include 'http://www.example.com/file.txt?foo=1&bar=2';
// Не сработает; будет искать файл 'file.php?foo=1&bar=2' в
// локальной файловой системе
include 'file.php?foo=1&bar=2';
// Сработает
include 'http://www.example.com/file.php?foo=1&bar=2';
?>Удалённые файлы могут быть обработаны на удалённой стороне (в зависимости от расширения файла и того, что удалённый сервер выполняет скрипты PHP или нет), но это всё равно должно производить корректный скрипт PHP, потому что он затем будет обработан уже на локальном сервере. Если файл с удалённого сервера должен быть обработан, а его результат только отображён, эффективнее воспользоваться функцией readfile(). В противном случае требуется соблюдать особую осторожность, чтобы обезопасить удалённый скрипт для получения корректного и желаемого кода.
Раздел «Удалённые файлы» и описания функций fopen() и file() дают дополнительную информацию.
Обработка возвращаемых значений: оператор include возвращает
значение FALSE, если возникла ошибка, и выдаёт предупреждение. Успешные
включения, пока это не переопределили во включаемом файле, возвращают значение
1. Допускается выполнять выражение return
внутри включаемого файла, чтобы завершить процесс выполнения в
этом файле и вернуться к выполнению включающего файла. Кроме того, возможно вернуть
значение из включаемых файлов. Можно получить значение включения, как
если бы вызвали обычную функцию. Хотя это невозможно при включении
удалённого файла, только если вывод удалённого файла не содержит
корректные теги начала и конца PHP
кода (так же, как и локальный файл). Разрешено определять необходимые
переменные внутри этих тегов и они будут представлены в зависимости от того,
какой файл был выключен.
Поскольку выражение include — специальная языковая конструкция,
круглые скобки не обязательны вокруг аргумента. При сравнении
возвращаемого значения соблюдают осторожность.
Пример #4 Сравнение значения, которое возвращает выражение include
<?php
// Не сработает, PHP интерпретирует как include(('vars.php') == TRUE), то есть include('1')
if (include('vars.php') == TRUE) {
echo 'OK';
}
// Cработает
if ((include 'vars.php') == TRUE) {
echo 'OK';
}
?>
Пример #5 Выражения include и return
return.php
<?php
$var = 'PHP';
return $var;
?>
noreturn.php
<?php
$var = 'PHP';
?>
testreturns.php
<?php
$foo = include 'return.php';
echo $foo; // выведет 'PHP'
$bar = include 'noreturn.php';
echo $bar; // выведет 1
?>
Значение переменной $bar равно 1, поскольку
инструкция успешно включила файл. Заметьте разницу между приведёнными примерами.
В первом записали return внутри включаемого файла, тогда как втором нет.
Если файл не получается включить, возвращается false и возникает
ошибка уровня E_WARNING.
Если во включаемом файле определили функции, эти функции можно вызывать в главном файле независимо от того, объявили ли функции до инструкции return или после. Если файл включат дважды, PHP выдаст фатальную ошибку, потому что функции уже определили. Рекомендуется использовать выражение include_once вместо проверки включения файла.
Другой путь «включить» PHP-файл в переменную — захватить
вывод функциями контроля вывода
вместе с выражением include. Например:
Пример #6 Буферизация вывода и включение файла PHP в строку
<?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;
}
?>Обратите внимание на конфигурационные директивы auto_prepend_file и auto_append_file в файле php.ini, чтобы включать файлы в скрипты автоматически.
Замечание: Поскольку это языковая конструкция, а не функция, её нельзя вызывать как переменную функцию или передавать как именованный аргумент.
Смотрите также описания функций require, require_once, include_once, get_included_files(), readfile(), virtual() и описание выражения include_path.