include_once

Оператор PHP include_once

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

На этой странице рассматриваются синтаксис, отличия include_once от include и require_once, возвращаемые значения и типичные случаи применения.

Синтаксис

include_once является языковой конструкцией, поэтому скобки необязательны:

include_once 'filename.php';
include_once('filename.php'); // also valid

PHP отслеживает файл по его разрешённому реальному пути. Поэтому include_once 'lib.php' и include_once './lib.php', указывающие на один и тот же файл на диске, считаются одним включением — второй вызов пропускается.

Как include_once решает, включать ли файл

Правило: один раз на запрос. Пример ниже использует tempnam() для создания реального файла во время выполнения, записи в него определения функции и последующего двукратного включения. Двукратное включение определения функции через обычный include привело бы к ошибке; include_once этого не допускает.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

Второй вызов include_once ничего не делает, так как файл уже был загружен, и функция greet() не объявляется повторно.

Возвращаемое значение

include_once возвращает 1 при первом включении (если файл не содержит явного return) и true, если файл уже был включён. Если файл не найден, генерируется предупреждение и возвращается false (скрипт не останавливается — для этого существует require_once).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

Файл также может возвращать значение, что удобно для файлов конфигурации:

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once в сравнении с другими конструкциями

В PHP есть четыре конструкции для включения файлов. Они различаются по двум параметрам — один раз или каждый раз и предупреждение или фатальная ошибка при отсутствии файла:

Используйте include_once, когда файл необязателен, но не должен загружаться дважды. Используйте require_once, когда файл обязателен (например, класс, без которого код не работает) и не должен загружаться дважды.

Когда использовать

• Библиотеки функций и классов. Любой файл, объявляющий функцию, класс или интерфейс, следует загружать через include_once (или require_once), чтобы исключить ошибку повторного объявления, даже если несколько частей приложения подключают его.
• Общие шапки и подвалы. Файл header.php, который должен отображаться один раз на странице.
• Константы и конфигурация. Файлы, использующие define() для определения констант — повторное определение константы вызывает предупреждение.

В современном PHP автозагрузчик Composer обычно заменяет ручное включение для классов, но include_once по-прежнему широко используется в устаревшем коде, шаблонах и небольших скриптах.

Распространённые подводные камни

• include_once защищает от двойного включения, а не от порядка загрузки. Он не решает магическим образом зависимости между файлами — он лишь предотвращает повторную загрузку одного и того же файла.
• Проверка «один раз» выполняется на каждый запрос, а не постоянно — каждый HTTP-запрос начинается с чистого состояния.
• Символические ссылки и различные относительные пути к одному файлу дедуплицируются по реальному пути, однако файл, доступный через два действительно разных пути (например, разные точки монтирования), может быть включён дважды.

Заключение

include_once включает файл ровно один раз за запрос, предотвращая фатальные ошибки повторного объявления и дублирование вывода. Используйте его (или require_once) всякий раз, когда файл определяет функции, классы или константы. Выбор между семействами include_* и require_* зависит от того, должно ли отсутствие файла приводить к восстанавливаемому предупреждению или к полной остановке скрипта.

Практика