include

(PHP 4, PHP 5, PHP 7, PHP 8)

Выражение include включает и оценивает код файла как PHP-код.

Документация текущего раздела также относится к выражению require.

Файлы включаются на основе заданного пути к файлу или, если путь не указали, на основе путей в директиве include_path. Перед выдачей ошибки выражение include проверит директорию текущего скрипта, в который включается файл, и текущую рабочую директорию, если PHP не нашёл файл в списке путей директивы include_path. Выражение include выдаст ошибку уровня E_WARNING, если не найдёт файл; поведение отличается от выражения require, которое выдаст фатальную ошибку E_ERROR.

Обратите внимание, при недоступности файла для чтения оба выражения выдадут дополнительную ошибку уровня E_WARNING перед выдачей окончательной ошибки уровня E_WARNING выражением include или ошибки уровня E_ERROR выражением require, которые возникают, когда PHP не находит файл.

PHP проигнорирует директиву include_path, если указали абсолютный путь (который начинается с буквы диска, или с обратного слеша \ в Windows и с прямого слеша / в Unix- и Linux-системах) или путь относительно текущей директории (который начинается с символа . или символов ..). Например, парсер будет искать запрошенный файл в родительской директории, если название файла начинается с ../.

Документация к директиве include_path подробнее рассказывает об обработке языком PHP включаемых файлов и путей.

После включения код включаемого файла наследует ту же область видимости переменных, что и строка, на которой включили файл. Переменные, которые доступны на этой строке во включающем файле, будут также доступны во включаемом файле. Однако функции и классы, которые объявили во включаемом файле, получат глобальную область видимости.

vars.php
<?php

$color = 'зелёное';
$fruit = 'яблоко';

?>

test.php
<?php

echo "Одно $color $fruit"; // Одно

include 'vars.php';

echo "Одно $color $fruit"; // Одно зелёное яблоко

?>

Внутри функции, в которой включают файл, код включаемого файла ведёт себя так, как будто его определили внутри функции; код последует области видимости переменных функции, в которую включается. Исключение к этому правилу — магические константы, которые выполняются парсером перед включением.

<?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-адреса аналогично передаче аргументов методом GET по протоколу HTTP, если целевой удалённый сервер интерпретирует целевой файл как PHP-код. Включение файла с удалённого сервера отличается от включения файла, который наследует родительскую область видимости файла, в который включается; скрипт выполняется на удалённом сервере, а результат затем включается в локальный скрипт.

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

?>

Раздел «Удалённые файлы» и описания функций fopen() и file() дают дополнительную информацию.

Обработка значений, которые возвращает выражение включения: при ошибке выражение include возвращает значение FALSE и выдаёт предупреждение. Успешные включения возвращают значение 1, если только значение возврата не переопределили включаемым файлом. Допускается выполнять инструкцию return внутри включаемого файла, чтобы завершить процесс выполнения во включаемом файле и вернуться к выполнению родительского файла. Из включаемых файлов также доступен возврат значения. Значение вызова включения получают так же, как если бы вызвали функцию. Невозможно получить значение вызова включения удалённого файла, если только вывод удалённого файла не содержит корректные теги начала и конца PHP-кода, как и с локальными файлами. Переменные, которые объявили внутри PHP-тегов, включатся в текущий скрипт в месте включения файла.

Поскольку выражение include относится к языковым конструкциям, круглые скобки вокруг аргумента необязательны. При сравнении значения, которое возвращает выражение включения файла, соблюдают осторожность.

<?php

// Не сработает, PHP интерпретирует выражение как include(('vars.php') == TRUE), то есть include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// Cработает
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}

?>

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. Например:

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