PHP Include

Введение

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

В этой главе рассматриваются все четыре оператора включения (include, require, include_once, require_once), их отличия, поведение подключённых переменных и функций, распространённые ошибки и лучшие практики, которые помогают поддерживать крупные проекты.

Зачем использовать включение файлов

Разделение кода на переиспользуемые файлы даёт три конкретных преимущества:

1. Меньше повторений. Напишите шапку, подвал или блок конфигурации один раз и подключайте его на столько страниц, сколько нужно. Отредактируйте в одном месте — и каждая страница обновится.
2. Упрощённое обслуживание. Исправление ошибки или изменение дизайна в общей разметке происходит в одном файле, а не на десятках страниц.
3. Лучшая организация. Разбивка большого скрипта на небольшие файлы с понятными именами (header.php, db.php, functions.php) делает кодовую базу более удобной для чтения и навигации.

Четыре оператора включения

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

Эмпирическое правило: используйте require (или require_once) для файлов, без которых страница не может работать — соединение с базой данных или определение класса. Используйте include для необязательных частей, например рекламного блока или боковой панели, которые приятно иметь, но не критичны.

Базовый синтаксис

<?php
// Include a file relative to the current script
include __DIR__ . '/header.php';

// Stop the page if a critical file is missing
require __DIR__ . '/db.php';

// Guarantee a file is loaded at most once
require_once __DIR__ . '/functions.php';
?>

__DIR__ — это магическая константа, которая указывает на директорию текущего файла. Построение путей на её основе позволяет работать включениям независимо от того, из какого каталога запускается скрипт — подробнее о магических константах в PHP Constants.

Зачем нужен суффикс _once

Если вы дважды подключите файл, в котором определены функция или класс, PHP выбросит фатальную ошибку «Cannot redeclare» при втором проходе. include_once и require_once отслеживают уже загруженные файлы и молча пропускают дубликаты, поэтому они являются безопасным вариантом по умолчанию для любого файла, объявляющего функции или классы.

<?php
require_once __DIR__ . '/functions.php'; // loads it
require_once __DIR__ . '/functions.php'; // skipped — no redeclare error
?>

Область видимости переменных в подключённых файлах

Подключённый файл выполняется в области видимости той строки, где он был подключён. Переменные, определённые до include, доступны внутри подключённого файла, а переменные, которые определяет подключённый файл, становятся доступны после.

<?php
// config.php
$siteName = "My Site";
$year = 2026;

<?php
// index.php
include __DIR__ . '/config.php';
echo "Welcome to $siteName ($year)";
// Output: Welcome to My Site (2026)
?>

Однако внутри функции переменные подключённого файла являются локальными для этой функции. Это часто сбивает с толку — файл конфигурации, подключённый внутри функции, не «утечёт» свои переменные в глобальную область видимости.

Возврат значения из подключённого файла

Подключённый файл может возвращать значение через return — это удобно для массивов конфигурации:

<?php
// settings.php
return [
    'debug'   => true,
    'timezone' => 'UTC',
];

<?php
// app.php
$config = include __DIR__ . '/settings.php';
echo $config['timezone']; // Output: UTC
?>

Обработка отсутствующих файлов

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

<?php
$sidebar = __DIR__ . '/sidebar.php';

if (file_exists($sidebar)) {
    include $sidebar;
} else {
    echo "<!-- sidebar unavailable -->";
}
?>

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

Лучшие практики

1. Используйте require_once для кода, include — для необязательного вывода. Определения функций и классов никогда не должны загружаться дважды; необязательные фрагменты UI могут деградировать без ошибок.
2. Строите пути от __DIR__. Избегайте относительных путей вроде include 'header.php', которые зависят от текущего рабочего каталога и могут неожиданно сломаться.
3. Называйте файлы по назначению. header.php, footer.php, db.php, auth.php — взглянув на имя файла, вы должны сразу понять, что внутри.
4. Держите подключаемые файлы сфокусированными. Одна ответственность на файл делает их удобными для повторного использования и понимания.
5. Никогда не подключайте путь, построенный из пользовательского ввода (например, include $_GET['page']). Это открывает уязвимость Local/Remote File Inclusion. Вместо этого используйте белый список допустимых значений.

Заключение

Семейство операторов include и require — это то, как PHP-проекты придерживаются принципа DRY: общая разметка, конфигурация и логика находятся в единственных файлах и подключаются в страницы по требованию. Используйте require/require_once, когда файл обязателен, include/include_once — когда необязателен, всегда привязывайте пути к __DIR__ и никогда не подключайте пути, контролируемые пользователем. Далее смотрите PHP Functions для организации переиспользуемой логики, которую вы обычно будете размещать в подключаемых файлах.

Диаграмма

graph TD;
A[PHP Page]-->B[Included File];

Практика