PHPTime

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
<?php
declare(strict_types=1);

$title = 'Каталог';

// Путь считается от каталога index.php.
include __DIR__ . '/views/header.php';

В views/header.php можно вывести заголовок. Переменная $title доступна шаблону, поскольку подключение выполнено в той же области видимости.

PHP
<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
<?php
declare(strict_types=1);

// Настройки возвращаются вызывающему скрипту.
return [
    'timezone' => 'UTC',
    'page_size' => 20,
];

Входной скрипт из того же каталога загружает настройки и применяет часовой пояс.

PHP
<?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
<?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
<?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
<?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];

Чек-лист подключения файлов

  1. Для обязательной зависимости выберите require. Для допустимого сбоя используйте include и предусмотрите обработку результата.
  2. Собирайте путь через __DIR__. Сверяйте регистр имени файла и права на чтение в окружении, где запускается PHP.
  3. Выбирайте require_once или include_once, когда код должен выполниться один раз. Для повторного вывода шаблона используйте обычное подключение.
  4. Получайте конфигурацию через return и передавайте прочитанное значение туда, где оно нужно.
  5. Для маршрутизации используйте список разрешённых файлов, а для классов проекта — автозагрузку.

Частые вопросы

Что лучше использовать в PHP: include или require?

Выбирайте require для файлов, без которых операция не может продолжаться, например для конфигурации или загрузчика классов. Include подходит, если ошибку открытия можно обработать и продолжить выполнение.

В чём разница между require_once и include_once в PHP?

Обе конструкции пропускают файл, если он уже был подключён в текущем выполнении. При сбое открытия require_once выбрасывает Error, а include_once выдаёт предупреждение и возвращает false.

Почему повторный require_once возвращает true вместо массива?

При повторном подключении PHP пропускает выполнение файла. Значение из его return можно получить при первом выполнении. Сохраните этот результат и используйте его там, где нужны данные.

Справка по теме

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин