(PHP 4, PHP 5, PHP 7, PHP 8)
Выражение include
включает и оценивает код файла как PHP-код.
Документация текущего раздела также относится к выражению require.
Файлы включаются на основе пути к файлу или, если путь не указали,
PHP ищет файлы по путям, которые определили в директиве
include_path. Перед выдачей ошибки
выражение include
проверит директорию текущего скрипта,
в который включается файл, и текущую рабочую директорию, если PHP не нашёл файл
в списке путей директивы include_path.
Выражение include
выдаст ошибку уровня E_WARNING
,
если не найдёт файл; поведение отличается от выражения require,
которое выдаст фатальную ошибку E_ERROR
.
Обратите внимание, что и выражение include
,
и выражение require
выдают дополнительную ошибку уровня E_WARNING
,
если к файлу невозможно получить доступ до выдачи последней ошибки уровня
E_WARNING
или E_ERROR
, соответственно.
PHP проигнорирует директиву include_path,
если указали абсолютный путь (который начинается с буквы диска,
или с обратного слеша \
в Windows и с прямого слеша /
в Unix- и Linux-системах) или путь относительно текущей директории (который начинается
с символа .
или символов ..
).
Например, парсер будет искать запрошенный файл в родительской директории,
если имя файла начинается с ../
.
Документация к директиве 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-кода.
PHP разрешает вместо локального пути указывать файлы для включения по URL-адресу, если разрешили работу URL-обёрток с include-выражениями. Файлы включают по HTTP-протоколу или через другие обработчики, которые поддерживает язык. Список протоколов, которые поддерживаются PHP, приводит страница «Протоколы и обёртки». Строка URL-запроса умеет передавать переменные во включаемый с удалённого сервера файл HTTP-методом GET, если целевой удалённый сервер интерпретирует целевой файл как PHP-код. Включение файла с удалённого сервера отличается от включения файла с наследованием включаемым файлом родительской области видимости включающего файла; скрипт выполняется на удалённом сервере, а результат затем включается в локальный скрипт.
Пример #3
Пример включения вывода, который сгенерировал скрипт удалённого сервера,
выражением include
через HTTP-запрос
<?php
/**
* В примере предполагается, что адрес www.example.com настроили на обработку
* файлов с расширением .php, но не .txt. Кроме того, «Сработает» здесь означает, что переменные
* $foo и $bar доступны внутри включаемого файла, и значения переменных определили при обработке переменных GET-запроса
*/
// Не сработает; файл 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';
// Сработает: удалённому скрипту будут доступны переменные $foo и $bar
include 'http://www.example.com/file.php?foo=1&bar=2';
?>
Удалённые серверы умеют обрабатывать удалённые файлы, в зависимости от расширения файла и того, запустили ли удалённый сервер с PHP, но требование к удалённому файлу создавать корректный PHP-скрипт остаётся, поскольку затем файл обработает локальный сервер. Лучше вызвать функцию readfile(), когда файл с удалённого сервера требуется обработать на удалённом сервере, а результат только вывести, иначе потребуется соблюдать повышенную осторожность, чтобы обезопасить удалённый скрипт от получения вредоносного кода.
Раздел «Удалённые файлы» и описания функций fopen() и file() дают дополнительную информацию.
Обработка значений, которые возвращает выражение включения: выражение include
возвращает
значение FALSE
, если возникла ошибка, и выдаёт предупреждение. Успешные
включения возвращают значение 1
, если только значение возврата
не переопределили включаемым файлом. Допускается выполнять выражение return
внутри включаемого файла, чтобы завершить процесс выполнения
во включаемом файле и вернуться к выполнению включающего файла. Кроме того, доступен возврат
значения из включаемых файлов. Значение вызова включения получают так же, как
если бы вызвали функцию. Невозможно получить значение вызова включения
удалённого файла, если только вывод удалённого файла не содержит
корректные теги начала и конца PHP-кода
, как и с локальными файлами. Переменные, которые объявили внутри 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.