require

Оператор require в PHP

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

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

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

Синтаксис

require — это языковая конструкция, а не функция, поэтому её можно записывать со скобками и без:

require '/path/to/file.php';
require('/path/to/file.php'); // also valid, but parentheses are unnecessary

На практике пути почти всегда должны быть относительными к текущему скрипту, а не к рабочему каталогу PHP. Магическая константа __DIR__ содержит каталог файла, в котором она используется, поэтому построение путей от неё гарантирует корректную работу require независимо от того, откуда запущен скрипт:

require __DIR__ . '/config.php';

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

Фрагмент ниже создаёт небольшой вспомогательный файл, подключает его и вызывает определённую в нём функцию. Можно вставить код в один .php-файл и запустить — вспомогательный файл записывается в тот же каталог во время выполнения, так что пример самодостаточен.

<?php

// Create a helper file next to this script.
file_put_contents(__DIR__ . '/greet.php', <<<'PHP'
<?php
function greet($name) {
    return "Hello, $name!";
}
PHP);

// Pull the helper in. After this line greet() is available.
require __DIR__ . '/greet.php';

echo greet('Ada'); // Hello, Ada!

Вывод:

Hello, Ada!

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

require vs include

Оба оператора загружают и выполняют файл. Единственное поведенческое различие — что происходит, когда файл отсутствует или недоступен:

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

require_once: избежать двойной загрузки

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

<?php
require_once __DIR__ . '/User.php'; // loads the file
require_once __DIR__ . '/User.php'; // already loaded — does nothing

Как правило, используйте require_once для файлов, которые объявляют что-либо (классы, библиотеки функций), и обычный require для файлов, которые намеренно выполняются более одного раза, например шаблон, рендеримый в цикле. Аналогичное разграничение «once/non-once» существует для include как include_once.

Типичные паттерны

Общий файл конфигурации, загружаемый в начале входного скрипта:

<?php
require __DIR__ . '/config.php';

// $dbHost, $dbUser, etc. defined in config.php are now available.
$pdo = new PDO("mysql:host=$dbHost", $dbUser, $dbPass);

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

// config.php
<?php
return [
    'host' => 'localhost',
    'port' => 3306,
];

// index.php
<?php
$config = require __DIR__ . '/config.php';
echo $config['port']; // 3306

Подводные камни

• Строите пути от __DIR__, а не от относительных строк. require 'config.php' разрешается относительно текущего рабочего каталога PHP, который может отличаться от расположения скрипта и незаметно сломаться при разных веб-серверах или вызовах через CLI.
• require выполняется в том месте, где он появляется. Если поместить его внутри функции (как в примере выше), загрузка откладывается до вызова этой функции, а переменные верхнего уровня файла ограничиваются областью видимости этой функции.
• Для классов предпочтительнее автозагрузчик. Ручное подключение десятков файлов классов чревато ошибками. Современные проекты используют vendor/autoload.php от Composer (загружается один раз через require) и доверяют PSR-4-автозагрузке подключение классов по требованию.

Заключение

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

Практика