require_once

Ключевое слово PHP require_once

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

На этой странице описаны синтаксис, механизм гарантии «только один раз», примеры с запуском кода, а также отличия require_once от require, include и include_once.

Синтаксис

Ключевое слово require_once включает и выполняет внешний PHP-файл, гарантируя, что он будет обработан только один раз. Вот базовый синтаксис:

Синтаксис PHP для require_once

require_once 'path/to/file.php';

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

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

Как работает гарантия «только один раз»

PHP ведёт внутренний список уже загруженных файлов (разрешённых до абсолютных путей). Когда интерпретатор встречает require_once, он сначала проверяет этот список:

• Если файл отсутствует в списке, PHP загружает и выполняет его, а затем добавляет в список.
• Если файл уже есть в списке, PHP ничего не делает и продолжает выполнение.

Именно это делает require_once безопасным для файлов, определяющих сущности. Следующие два файла демонстрируют это. helpers.php определяет функцию и выводит строку, чтобы мы могли видеть, когда файл действительно выполняется:

<?php
// helpers.php
echo "helpers.php is being loaded\n";

function greet($name)
{
    return "Hello, $name!";
}

<?php
// main.php
require_once 'helpers.php';
require_once 'helpers.php'; // second request is silently skipped

echo greet("World") . "\n";

Выполнение main.php выводит:

helpers.php is being loaded
Hello, World!

Строка "helpers.php is being loaded" появляется только один раз, несмотря на то что файл был запрошен дважды — и второй запрос не повторно объявил greet(), что иначе привело бы к фатальной ошибке.

Примеры

Рассмотрим несколько практических примеров использования ключевого слова require_once:

Примеры PHP require_once

<?php

// Example 1
require_once 'config.php';

// Example 2
function myFunction()
{
  require_once 'helpers.php';
  // Code block here
}

Оба примера включают и выполняют внешние файлы ровно один раз. Это предотвращает ошибки, возникающие при двойной загрузке файла — чаще всего повторное объявление функции или класса.

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

require_once в сравнении с другими ключевыми словами включения

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

Варианты с _once существуют именно для того, чтобы избежать повторного выполнения файла. При использовании обычного require двойной запрос helpers.php выполнит его дважды — и второй раз завершится фатальной ошибкой при попытке повторно объявить greet():

PHP Fatal error: Cannot redeclare function greet() ...

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

Преимущества

Использование ключевого слова require_once имеет ряд преимуществ:

• Предотвращение ошибок: гарантирует, что файл обрабатывается только один раз, исключая фатальные ошибки, связанные с повторным объявлением функций, классов или трейтов.
• Эффективное использование ресурсов: предотвращает избыточную загрузку и разбор файлов. (Примечание: PHP поддерживает небольшие накладные расходы на отслеживание включённых файлов, но они, как правило, незначительны по сравнению со стоимостью повторного разбора больших файлов.)

Заключение

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

Практика