include

Оператор PHP include

include включает содержимое другого PHP-файла в текущий скрипт и выполняет его в том месте, где находится оператор. Концептуально PHP копирует включаемый файл на место, вычисляет его в том же области видимости и продолжает выполнение. Именно так можно избежать повторения общей разметки и логики — заголовков, подвалов, навигации, конфигурации и многократно используемых функций — на множестве страниц.

На этой странице рассматриваются синтаксис, принципы работы области видимости, возвращаемое значение include, отличие от require и распространённые ошибки, которых следует избегать.

Синтаксис

include 'filename.php';

Путь может быть относительным или абсолютным. include является языковой конструкцией, а не функцией, поэтому скобки необязательны — include 'file.php'; и include('file.php'); работают одинаково.

Когда PHP выполняет include, он ищет файл в следующем порядке: по указанному пути (если путь относительный, он разрешается относительно текущего рабочего каталога и настройки include_path), затем в каталоге выполняемого скрипта. Чтобы подключение работало надёжно независимо от того, откуда запускается скрипт, привяжите пути к текущему файлу:

include __DIR__ . '/partials/header.php';

__DIR__ — это каталог файла, содержащего данный оператор, поэтому подключение разрешается корректно даже при запуске скрипта из другого каталога.

Рабочий пример

Поскольку include работает с отдельными файлами, наглядный способ увидеть его в действии — создать эти файлы во время выполнения. Фрагмент ниже записывает небольшой частичный шаблон, подключает его и выводит результат — он полностью работоспособен как единый скрипт:

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

Включаемый файл может читать $name, потому что include использует общую область видимости. Это самое важное, что нужно понять об include: это не изолированная модульная система. Все переменные, существующие до include, доступны во включаемом файле, а переменные, определённые во включаемом файле, просачиваются обратно в вызывающий контекст.

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

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

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Если включаемый файл не выполняет return, выражение include принимает значение 1 в случае успеха.

include vs require (и варианты с _once)

В PHP есть четыре связанных оператора. Все они подключают файл; они различаются поведением при сбое и тем, пропускаются ли повторные подключения.

Практические правила:

• Используйте require для файлов, без которых скрипт не может работать (файл конфигурации, определение класса, подключение к базе данных). Быстрый сбой с фатальной ошибкой безопаснее, чем продолжение работы в сломанном состоянии.
• Используйте include для необязательных элементов, таких как боковой виджет или рекламный блок, когда отсутствующий файл не должен разрушать всю страницу.
• Используйте варианты с _once, когда повторное подключение файла может вызвать ошибки — чаще всего в случаях, когда файл объявляет функции или классы, поскольку их повторное объявление является фатальной ошибкой.

Распространённые ошибки

• Доверие пользовательскому вводу в пути. Никогда не передавайте нефильтрованные данные запроса в include (например, include $_GET['page'] . '.php';). Это открывает путь к атакам через включение локальных файлов. Вместо этого проверяйте значение по белому списку известных файлов.
• Относительные пути, которые ломаются. Простое include 'header.php'; зависит от текущего рабочего каталога и может завершиться ошибкой при вызове скрипта из другого места. Предпочитайте пути, привязанные к __DIR__.
• Повторное объявление функций или классов. Если файл, определяющий функции, подключается дважды через обычный include, PHP выдаёт фатальную ошибку "Cannot redeclare". Используйте include_once для таких файлов.
• Предположение об изоляции. Поскольку область видимости является общей, включаемый файл может перезаписать ваши переменные. Делайте подключения сосредоточенными и предсказуемыми.

Зачем использовать include

• Повторное использование — определите общую разметку или логику один раз и подключайте её на каждую страницу, которой это нужно.
• Удобство сопровождения — измените навигацию в одном шаблоне и все страницы обновятся.
• Структурирование — разбейте большое приложение на небольшие, сосредоточенные файлы вместо одного монолита.

Связанные темы

• PHP require и require_once — аналоги с жёстким завершением при ошибке.
• PHP include_once — подключение файла не более одного раза.
• PHP Functions — то, что обычно размещают в общих подключаемых файлах.
• PHP File Handling — чтение и запись файлов во время выполнения.

Практика