include_once

La sentencia include_once de PHP

include_once incluye y evalúa un archivo durante la ejecución, pero solo si ese archivo no ha sido incluido previamente en la solicitud actual. Si el mismo archivo se solicita de nuevo con include_once, PHP lo omite silenciosamente. Esto lo convierte en la opción segura para archivos que definen funciones, clases o constantes — incluir dicho archivo dos veces provocaría de otro modo un error fatal de "no se puede redeclarar".

Esta página cubre la sintaxis, cómo include_once difiere de include y require_once, qué devuelve, y los casos habituales en los que realmente se utiliza.

Sintaxis

include_once es una construcción del lenguaje, por lo que los paréntesis son opcionales:

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

PHP rastrea el archivo por su ruta real resuelta. Así que include_once 'lib.php' y include_once './lib.php' que apuntan al mismo archivo en disco se tratan como la misma inclusión — la segunda se omite.

Cómo include_once decide si incluir

La regla es una inclusión por solicitud. El ejemplo siguiente usa tempnam() para crear un archivo real en tiempo de ejecución, escribir en él una definición de función y luego incluirlo dos veces. Incluir una definición de función dos veces con include simple provocaría un fallo; include_once no lo hace.

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

El segundo include_once no hace nada porque el archivo ya fue cargado, por lo que greet() nunca se redeclara.

Valor de retorno

include_once devuelve 1 en una inclusión nueva (cuando el archivo no tiene un return explícito), y true si el archivo ya fue incluido. Si el archivo no se puede encontrar, emite una advertencia y devuelve false (no detiene el script — para eso existe require_once).

<?php

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

// Output:
// bool(false)

Un archivo también puede devolver un valor, lo que es útil para archivos de configuración:

<?php

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

include_once frente a las otras tres

PHP dispone de cuatro construcciones de inclusión de archivos. Se diferencian en dos ejes — una vez o cada vez y advertencia o error fatal si falta el archivo:

Usa include_once cuando el archivo es opcional pero no debe cargarse dos veces. Usa require_once cuando el archivo es esencial (una clase sin la que el código no puede funcionar) y no debe cargarse dos veces.

Cuándo usarlo

• Bibliotecas de funciones y clases. Cualquier archivo que declare una función, clase o interfaz debe cargarse con include_once (o require_once) para que sea imposible un error de redeclaración, incluso si varias partes de la aplicación lo importan.
• Encabezados y pies de página compartidos. Un header.php que debe renderizarse una sola vez por página.
• Constantes y configuración. Archivos que usan define() para definir constantes — redefinir una constante genera una advertencia.

En PHP moderno, el autocargador de Composer suele reemplazar la inclusión manual para clases, pero include_once sigue estando en todas partes en código heredado, plantillas y scripts pequeños.

Errores comunes

• Protege contra la doble inclusión, no el orden de carga. include_once no resuelve mágicamente las dependencias entre archivos; solo impide que el mismo archivo se cargue dos veces.
• La comprobación "once" es por solicitud, no persistente — cada solicitud HTTP comienza con un estado limpio.
• Los enlaces simbólicos y las diferentes rutas relativas al mismo archivo se deduplican por ruta real, pero un archivo accesible a través de dos rutas genuinamente diferentes (p. ej., distintos puntos de montaje) puede incluirse dos veces.

Conclusión

include_once incluye un archivo exactamente una vez por solicitud, evitando errores fatales de redeclaración y salidas duplicadas. Úsalo (o require_once) siempre que un archivo defina funciones, clases o constantes. Elige entre las familias include_* y require_* según si un archivo que falta debe ser una advertencia recuperable o una detención definitiva.

Práctica