(PHP 4, PHP 5, PHP 7)
Выражение include включает и выполняет указанный файл.
Документация ниже также относится к выражению require.
Файлы включаются исходя из пути указанного файла, или, если путь не указан, используется путь, указанный в директиве include_path. Если файл не найден в include_path, include попытается проверить директорию, в которой находится текущий включающий скрипт и текущую рабочую директорию перед тем, как выдать ошибку. Конструкция include выдаст предупреждение, если не сможет найти файл; поведение отлично от require, который выдаст фатальную ошибку.
Если путь указан — абсолютный (начинающийся с буквы диска или с \ в Windows или с / в Unix/Linux системах) или относительно текущей директории (начинающийся с . или ..) — include_path будет проигнорирован вообще. Например, если имя файла начинается с ../, парсер будет искать в родительской директории запрошенный файл.
Для дополнительной информации о том, как PHP обрабатывает включаемые файлы и включаемые пути, смотрите документацию для директивы include_path.
Когда файл включается, его код наследует ту же область видимости переменых, что и строка, на которой произошло включение. Все переменные, доступные на этой строке во включающем файле, будут также доступны во включаемом файле. Однако все функции и классы, объявленные во включаемом файле, имеют глобальную область видимости.
Пример #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';
$foo = 1;
$bar = 2;
include 'file.txt'; // Сработает.
include 'file.php'; // Сработает.
?>
Удаленные файлы могут быть обработаны на удаленной стороне (в зависимости от расширения файла и того, что удаленный сервер выполняет скрипты PHP или нет), но это все равно должно производить корректный скрипт PHP, потому что он будет затем обработан уже на локальном сервере. Если файл с удаленного сервера должен быть обработан и только отображен его результат, гораздо эффективно воспользоваться функцией readfile() В противном случае следует соблюдать особую осторожность, чтобы обезопасить удаленный скрипт для получения корректного и желаемого кода.
Смотрите также раздел Удаленные файлы, функции fopen() и file() для дополнительной информации.
Обработка возвращаемых значений: оператор include возвращает значение FALSE при ошибке и выдает предупреждение. Успешные включения, пока это не переопределено во включаемом файле, возвращают значение 1. Возможно выполнить выражение return внутри включаемого файла, чтобы завершить процесс выполнения в этом файле и вернуться к выполнению включающего файла. Кроме того, возможно вернуть значение из включаемых файлов. Вы можете получить значение включения, как если бы вы вызвали обычную функцию. Хотя это невозможно при включении удаленного файла, только если вывод удаленного файла не содержит корректные теги начала и конца PHP кода (так же, как и локальный файл). Вы можете определить необходимые переменные внутри этих тегов и они будут представлены в зависимости от того, какой файл был выключен.
Так как include - это специальная языковая конструкция, круглые скобки не обязательны вокруг аргумента. Будьте внимательны при сравнении возвращаемого значения.
Пример #4 Сравнение возвращаемого значения при include
<?php
// не сработает, интерпретируется как include(('vars.php') == TRUE), то есть include('')
if (include('vars.php') == TRUE) {
echo 'OK';
}
// сработает
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 5 выдаст фатальную ошибку, потому что функции уже были определены, в то время как PHP 4 не обратил бы внимания на функции, определенные после return. Рекомендуется использовать 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.