require

La sentencia require de PHP

En PHP, require toma el contenido de otro archivo PHP, lo inserta en el punto donde aparece require y lo evalúa como si hubiera sido escrito allí. Es la forma en que los proyectos PHP dividen el código en múltiples archivos: la configuración, las funciones auxiliares, las definiciones de clases y las plantillas residen cada una en su propio archivo y se incorporan con require.

Lo que diferencia a require de su equivalente include es cómo reacciona ante un archivo faltante. Si el archivo de destino no se encuentra, require detiene el script con un error fatal, mientras que include solo emite una advertencia y continúa. Eso hace que require sea la opción correcta para los archivos sin los cuales el script no puede ejecutarse.

Esta guía cubre la sintaxis, ejemplos ejecutables, la diferencia entre require e include, cuándo usar require_once y los errores comunes en los que la gente tropieza.

Sintaxis

require es una construcción del lenguaje, no una función, por lo que puedes escribirla con o sin paréntesis:

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

En la práctica, casi siempre querrás que las rutas sean relativas al script actual en lugar del directorio de trabajo de PHP. La constante mágica __DIR__ contiene el directorio del archivo en el que aparece, por lo que construir rutas a partir de ella mantiene require funcionando sin importar desde dónde se ejecute el script:

require __DIR__ . '/config.php';

Un ejemplo ejecutable

El fragmento a continuación crea un pequeño archivo auxiliar, lo requiere y luego llama a la función que define. Puedes pegarlo en un único archivo .php y ejecutarlo — el archivo auxiliar se escribe en el mismo directorio en tiempo de ejecución, por lo que el ejemplo es autocontenido.

<?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!

Salida:

Hello, Ada!

Una vez que se requiere un archivo, todo lo que declara — funciones, clases y cualquier variable de nivel superior — pasa a formar parte del ámbito actual, exactamente como si lo hubieras escrito en línea.

require vs include

Ambas sentencias cargan y evalúan un archivo. La única diferencia de comportamiento es lo que ocurre cuando el archivo falta o no se puede leer:

Usa require para cosas como un archivo de conexión a la base de datos o un autoloader, donde continuar sin ellos no tiene sentido. Recurre a include solo cuando un archivo faltante deba tolerarse — por ejemplo, una anulación de tema opcional.

require_once: evitar cargar dos veces

Requerir el mismo archivo dos veces causa problemas: redeclarar una función o clase es en sí mismo un error fatal. require_once resuelve esto recordando qué archivos ya se han cargado y omitiendo cualquier solicitud repetida.

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

Como regla general, usa require_once para los archivos que definen cosas (clases, bibliotecas de funciones) y require simple para los archivos que intencionalmente ejecutas más de una vez, como una plantilla renderizada en un bucle. La misma distinción entre once/non-once existe para include como include_once.

Patrones comunes

Un archivo de configuración compartido cargado al inicio de un script de entrada:

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

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

Un archivo requerido también puede return un valor, que require evalúa. Esta es una forma limpia de cargar un array de configuración:

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

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

Errores comunes

• Construye rutas desde __DIR__, no desde cadenas relativas. require 'config.php' se resuelve contra el directorio de trabajo actual de PHP, que puede diferir de la ubicación del script y fallar silenciosamente bajo diferentes servidores web o invocaciones de CLI.
• require se ejecuta en el punto donde aparece. Colocarlo dentro de una función (como en el ejemplo anterior) aplaza la carga hasta que se llama a esa función, y limita las variables de nivel superior del archivo al ámbito de esa función.
• Prefiere un autoloader para las clases. Requerir manualmente decenas de archivos de clases es propenso a errores. Los proyectos modernos usan vendor/autoload.php de Composer (cargado una vez con require) y dejan que la autocarga PSR-4 incorpore las clases bajo demanda.

Conclusión

require es la base de la organización del código en PHP: divide un programa en archivos enfocados y carga los que un script necesita, fallando ruidosamente si alguno falta. Construye rutas desde __DIR__, elige require_once para las definiciones y evitar la doble carga, y recurre a include solo cuando un archivo faltante sea aceptable. Para las bibliotecas de clases, un autoloader de Composer es el reemplazo moderno de las listas de require escritas a mano.

Práctica