require_once

La palabra clave require_once de PHP

require_once incluye y evalúa un archivo PHP externo en el punto donde se escribe la instrucción — pero solo la primera vez que se solicita ese archivo. Si el mismo archivo se solicita nuevamente más adelante en la misma solicitud, PHP lo omite. Esto hace que require_once sea la forma más segura de incluir archivos que definen funciones, clases, traits o constantes, ya que cargarlos una segunda vez haría que el script fallara fatalmente.

Esta página cubre la sintaxis, cómo funciona la garantía "once", ejemplos ejecutables, y en qué se diferencia require_once de require, include e include_once.

Sintaxis

La palabra clave require_once incluye y evalúa un archivo PHP externo, asegurando que solo se procese una vez. Esta es la sintaxis básica:

La sintaxis PHP de require_once

require_once 'path/to/file.php';

Esto incluye y evalúa el contenido de path/to/file.php, pero solo si no ha sido incluido ya durante esta solicitud. Como es una construcción del lenguaje (no una función), los paréntesis son opcionales — require_once 'file.php'; y require_once('file.php'); se comportan igual.

Nota: Si el archivo especificado no se puede encontrar, require_once genera un error fatal y detiene el script. Su contraparte include_once solo emite una advertencia y permite que el script continúe.

Cómo funciona la garantía "solo una vez"

PHP mantiene una lista interna de los archivos que ya ha cargado (resueltos a sus rutas absolutas). Cuando llega a un require_once, primero verifica esa lista:

• Si el archivo no está en la lista, PHP lo carga y ejecuta, luego lo agrega a la lista.
• Si el archivo ya está en la lista, PHP no hace nada y continúa.

Esto es lo que hace que require_once sea seguro para archivos que definen elementos. Los dos archivos siguientes lo demuestran. helpers.php define una función e imprime una línea para que podamos ver cuándo se ejecuta realmente:

<?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";

Ejecutar main.php imprime:

helpers.php is being loaded
Hello, World!

La línea "helpers.php is being loaded" aparece solo una vez, aunque el archivo fue solicitado dos veces — y la segunda solicitud no redeclaró greet(), lo que de otro modo habría causado un error fatal.

Ejemplos

Veamos algunos ejemplos prácticos de cómo se puede usar la palabra clave require_once:

Ejemplos de PHP require_once

<?php

// Example 1
require_once 'config.php';

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

Ambos ejemplos incluyen y evalúan archivos externos exactamente una vez. Esto evita los errores que ocurren cuando un archivo se carga dos veces — más comúnmente al redefinir una función o una clase.

Nota: Aunque require_once se puede colocar dentro de una función, el seguimiento de inclusiones de PHP es global para toda la solicitud. Por lo general, se prefiere la colocación en el nivel superior; recurra a la inclusión dentro de funciones solo cuando la carga deba ser condicional.

require_once vs las otras palabras clave de inclusión

PHP tiene cuatro construcciones de inclusión. Se diferencian en dos ejes independientes: qué sucede al fallar, y si el archivo puede cargarse más de una vez.

Las variantes _once existen precisamente para evitar volver a ejecutar un archivo. Con require simple, solicitar helpers.php dos veces lo ejecuta dos veces — y la segunda ejecución falla fatalmente al intentar redeclarar greet():

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

Regla general: use require_once para archivos que definen elementos (bibliotecas de funciones, clases, configuración que no debe ejecutarse dos veces); use include para archivos que solo producen salida, como un encabezado de página reutilizable que se renderiza intencionalmente varias veces.

Beneficios

El uso de la palabra clave require_once tiene varios beneficios, entre ellos:

• Prevención de errores: Asegura que un archivo solo se procese una vez, evitando errores fatales por redeclarar funciones, clases o traits.
• Uso eficiente de recursos: Evita la carga y análisis redundante de archivos. (Nota: PHP mantiene una pequeña sobrecarga de seguimiento para los archivos incluidos, pero esto generalmente se ve compensado por el costo de volver a analizar archivos grandes.)

Conclusión

En conclusión, require_once es una herramienta confiable para incluir archivos PHP externos evitando el procesamiento duplicado y los errores fatales. Úselo cuando un archivo deba cargarse exactamente una vez, y elija require o include cuando necesite un manejo de errores diferente o quiera evitar la sobrecarga de seguimiento. Esperamos que esta guía le ayude a escribir código PHP más robusto.

Práctica