include и require в PHP: в чём разница и как подключать файлы
В PHP конструкции include и require выполняют код из другого файла. Если файл недоступен, include выдаёт предупреждение и возвращает false, а require в PHP 8 выбрасывает Error. Варианты с _once пропускают файлы, которые уже подключались в текущем выполнении скрипта.
Чем отличаются include и require в PHP
include, require, include_once и require_once — конструкции языка. Скобки вокруг пути необязательны. Все четыре выполняют подключаемый файл непосредственно в месте вызова, поэтому он может объявить функции и классы, вывести HTML или вернуть значение.
| Конструкция | Если файл не удалось открыть | Если файл уже подключён |
|---|---|---|
include | Предупреждение E_WARNING и результат false | Выполняет файл повторно |
require | Ошибка Error, открытие файла также может вызвать предупреждение | Выполняет файл повторно |
include_once | Предупреждение E_WARNING и результат false | Пропускает выполнение, возвращает true |
require_once | Ошибка Error, открытие файла также может вызвать предупреждение | Пропускает выполнение, возвращает true |
Используйте require для обязательной конфигурации, загрузчика классов и частей страницы, без которых ответ нельзя собрать. Используйте include, если сбой подключения допустим и приложение может обработать результат false. При ожидаемом отсутствии файла, например локального шаблона переопределения, проверяйте наличие и явно выбирайте запасной вариант.
Разница в таблице касается открытия файла. Синтаксическая ошибка в доступном файле вызывает ParseError при любой из четырёх конструкций. Исключение, выброшенное внутри файла, также передаётся вызывающему коду.
PHP include: как указать путь к файлу
Для файлов своего проекта стройте путь от __DIR__. Эта константа содержит каталог файла, в котором написана, поэтому результат сохраняется при запуске через веб-сервер, CLI или другой входной скрипт. Например, если index.php и каталог views находятся в одном каталоге, подключение выглядит так.
<?php
declare(strict_types=1);
$title = 'Каталог';
// Путь считается от каталога index.php.
include __DIR__ . '/views/header.php';В views/header.php можно вывести заголовок. Переменная $title доступна шаблону, поскольку подключение выполнено в той же области видимости.
<h1><?= htmlspecialchars($title, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') ?></h1>- Абсолютный путь и пути с префиксом
./или../обходят поиск поinclude_path. Префиксы./и../отсчитываются от текущего рабочего каталога. - Имя без явного пути, например
'header.php', PHP ищет поinclude_path. Если поиск не дал результата, PHP проверяет каталог вызывающего файла и текущий рабочий каталог. __DIR__во вложенном файле указывает на каталог этого вложенного файла. Еслиheader.phpподключает соседнийnav.php, используйте__DIR__ . '/nav.php'уже внутриheader.php.
При диагностике сравните путь, собранный из __DIR__, с рабочим каталогом из getcwd(). Это особенно полезно, когда скрипт работает из терминала, а при запуске по расписанию теряет относительные пути.
Require в PHP: обязательные файлы и возврат значения
Файл может вернуть данные через return. Такой формат удобен для конфигурации: вызывающий код явно получает массив, а переменные конфигурации остаются частью возвращаемой структуры. Например, config.php содержит следующий код.
<?php
declare(strict_types=1);
// Настройки возвращаются вызывающему скрипту.
return [
'timezone' => 'UTC',
'page_size' => 20,
];Входной скрипт из того же каталога загружает настройки и применяет часовой пояс.
<?php
declare(strict_types=1);
$config = require __DIR__ . '/config.php';
date_default_timezone_set($config['timezone']);При успешном выполнении файла без явного return обычные include и require возвращают целое число 1. return завершает выполнение подключаемого файла, после чего вызывающий скрипт продолжается. Если сам файл может вернуть false, по результату include нельзя отличить это значение от ошибки открытия.
require гарантирует, что выполнение дойдёт до следующей строки только при нормальном завершении подключения. Формат результата задаёт сам файл. Если конфигурацию поставляет отдельный компонент, проверяйте ожидаемые ключи и типы на границе загрузки. Вывод через echo или HTML вне PHP-тегов сразу попадает в поток вывода. В файлах настроек и библиотек оставляйте открывающий <?php и опускайте закрывающий ?>, чтобы случайные пробелы не мешали отправке HTTP-заголовков.
Require once и include once в PHP: однократное подключение
Имена конструкций пишутся с подчёркиванием: require_once и include_once. PHP учитывает ранее подключённые файлы в рамках текущего выполнения, даже если первый вызов был через обычный include или require. Два вызова require_once в разных функциях тоже могут ссылаться на один уже подключённый файл.
require_once подходит для файла с объявлениями, который должен быть доступен нескольким точкам входа. Повторное выполнение обычного require для такого файла может привести к ошибке повторного объявления. Если проект использует Composer, из точки входа обычно подключают его загрузчик, а классы загружаются по правилам автозагрузки.
<?php
declare(strict_types=1);
// Файл появляется после установки зависимостей Composer.
require_once __DIR__ . '/vendor/autoload.php';include_once подходит для необязательного файла инициализации, который следует выполнить один раз. Например, главный скрипт и административный модуль могут подключать локальный файл настройки диагностики. Если отсутствие файла штатно, проверяйте его наличие перед вызовом, чтобы избежать предупреждения. Однократность действует в пределах исполнения PHP. В обычном веб-приложении следующий запрос выполняет инициализацию заново, а в долгоживущем процессе повторный вызов в следующей итерации пропустит уже подключённый файл.
Сохраняйте результат первого подключения файла данных. Если дважды присвоить $config = require_once __DIR__ . '/config.php';, первый вызов вернёт массив из примера, а второй присвоит true. Для повторяющихся шаблонов, например карточек в списке, используйте обычный require или include, чтобы шаблон отрисовался для каждой записи.
Область видимости и строгая типизация
Код файла видит переменные в месте подключения. Вызов на верхнем уровне даёт доступ к переменным верхнего уровня, а вызов внутри функции — к её локальным переменным. Шаблон может прочитать или изменить эти переменные. Именованные функции и классы, объявленные при подключении, доступны по своим именам с учётом пространства имён, заданного в их файле.
<?php
declare(strict_types=1);
function renderHeader(string $title): void
{
// views/header.php получает локальную переменную $title.
require __DIR__ . '/views/header.php';
}
renderHeader('Каталог');Директива declare(strict_types=1) действует в файле, где объявлена. Для скалярных аргументов важен файл, в котором сделан вызов. Например, если подключённый PHP-файл сам вызывает функцию с параметром int, строгость этого вызова определяется директивой в подключённом файле. Для проверки скалярного возвращаемого значения важен файл, где определена функция. При необходимости ставьте директиву первым оператором каждого PHP-файла с прикладным кодом.
Ошибки подключения и поведение в PHP 8.3–8.5
В PHP 8.3, 8.4 и 8.5 описанная семантика одинакова. При невозможности открыть обязательный файл require и require_once выбрасывают Error. Это поведение действует с PHP 8.0. До PHP 8.0 такой сбой завершался ошибкой уровня E_COMPILE_ERROR. В PHP 8 необработанный Error останавливает выполнение, а catch (Exception $e) его не перехватывает. На границе приложения для обработки и Error, и исключений используют catch (Throwable $e). Предупреждения об открытии файла обрабатываются отдельно средствами обработки ошибок PHP.
Failed to open stream
Проверьте абсолютный путь и регистр имени файла. Код, работающий на файловой системе без учёта регистра, может сломаться на Linux при несовпадении Header.php и header.php. Затем проверьте, что файл попал в сборку, доступен пользователю процесса PHP на чтение и находится в пределах open_basedir, если это ограничение задано. Для отладки полезна функция get_included_files(), которая показывает уже подключённые файлы.
Cannot redeclare и неожиданный результат true
При Cannot redeclare проверьте, откуда загружается файл с объявлениями. Для одного файла помогает require_once, для классов обычно удобнее автозагрузка. Если одно имя объявлено в двух разных файлах, исправьте конфликт имён или пространств имён. Если вместо массива настроек получен true, проверьте, не выполнялся ли раньше вызов с _once для того же файла.
Путь приходит из запроса
Передавайте из запроса ключ страницы. Путь к шаблону выбирайте из фиксированного списка внутри приложения. Прямая подстановка параметра запроса в путь позволяет атакующему выбирать файлы для подключения. Для шаблонов держите на сервере только файлы, которые приложению разрешено исполнять.
<?php
declare(strict_types=1);
$views = [
'home' => __DIR__ . '/views/home.php',
'help' => __DIR__ . '/views/help.php',
];
$page = $_GET['page'] ?? 'home';
// Запрос может выбрать только ключ из списка.
if (!is_string($page) || !isset($views[$page])) {
http_response_code(404);
exit('Страница не найдена');
}
require $views[$page];Чек-лист подключения файлов
- Для обязательной зависимости выберите
require. Для допустимого сбоя используйтеincludeи предусмотрите обработку результата. - Собирайте путь через
__DIR__. Сверяйте регистр имени файла и права на чтение в окружении, где запускается PHP. - Выбирайте
require_onceилиinclude_once, когда код должен выполниться один раз. Для повторного вывода шаблона используйте обычное подключение. - Получайте конфигурацию через
returnи передавайте прочитанное значение туда, где оно нужно. - Для маршрутизации используйте список разрешённых файлов, а для классов проекта — автозагрузку.
Частые вопросы
Что лучше использовать в PHP: include или require?
Выбирайте require для файлов, без которых операция не может продолжаться, например для конфигурации или загрузчика классов. Include подходит, если ошибку открытия можно обработать и продолжить выполнение.
В чём разница между require_once и include_once в PHP?
Обе конструкции пропускают файл, если он уже был подключён в текущем выполнении. При сбое открытия require_once выбрасывает Error, а include_once выдаёт предупреждение и возвращает false.
Почему повторный require_once возвращает true вместо массива?
При повторном подключении PHP пропускает выполнение файла. Значение из его return можно получить при первом выполнении. Сохраните этот результат и используйте его там, где нужны данные.