Diferencias entre include, require, include_once y require_once en PHP

Este tema, es un tema que genera muchas dudas entre programadores principiantes y también a veces, en programadores no tan principiantes.

Eh, yo era uno de ellos y aunque parezca fácil (realmente lo es), me costó bastante metérmelo en “la cogotera”. Como ya sabes o si eres nuevo en PHP, lo habitual es dividir el código en varios archivos para mantener una estructura más organizada, por ejemplo, cabecera; pie de página, clases de configuración, etc. Por cierto, también puede interesarte leer este post de aquí.

Para poder reutilizar ese código en distintos lugares, PHP nos ofrece varias funciones de inclusión: include, require, include_once y require_once.

Todas ellas parecen similares, pero existen diferencias clave entre ellas que pueden afectar al funcionamiento de una aplicación.

El objetivo de este artículo es analizar qué hace cada una, sus diferencias y cuándo conviene usar una u otra.

¡Al lio!

Include

La documentación oficial de PHP es bastante clara:

“La expresión de lenguaje include incluye y ejecuta el fichero especificado en argumento.”

Más claro imposible, bueno si, espera:

“El comando include inserta el contenido de otro archivo en el script actual en el punto en que se llama.” 😉

Un ejemplo:

<?php
// include
include 'header.php';
echo "Contenido principal";
include 'footer.php';

Y aquí es donde entra la diferencia; si el archivo especificado no se encuentra o no se puede incluir, PHP mostrará una advertencia (warning), pero seguirá ejecutando el resto del código.

Esto puede ser útil cuando el archivo no es esencial para la ejecución del programa, pero podría causar problemas si se necesita para una función crítica.

Require

La función require, funciona igual que include, solo que en vez de mostrar una advertencia en caso de que no exista o no se pueda cargar el archivo, detendrá la ejecución actual del script y mostrará un error fatal.

Ejemplo de uso:

<?php
// require
require 'config.php';
echo "Esto nunca se ejecutará si config.php no existe.";

Entonces, ¿Cuándo usamos uno u otro?

Si consideramos que el archivo a incluir es esencial para el funcionamiento de nuestro programa, como por ejemplo archivos de configuración, autoloader, archivos que conectan con alguna base de datos, etc. Podemos considerar usar require en lugar de include. Dado que, si falla la carga de alguno de esos archivos, lo normal es detener el programa, o en otras palabras, no continuar con la ejecución del mismo.

Resumiendo:

include: lanza advertencia (warning) y continúa.

require: error fatal y se detiene la ejecución.

Include_once

Como su propio nombre indica, ya sabes, “once” es igual a “una vez” en inglés 😎 include_once hace lo mismo que include, pero evita incluir el mismo archivo más de una vez. De esa manera, nos aseguramos que se redefinan funciones o clases. En otras palabras, evitamos que se incluya el mismo código, misma función o misma clase más de una vez, evitando problemas o errores como el:

Fatal error: Cannot redeclare function()

Gracias a include_once garantizamos que un archivo se incluya solo una vez durante la ejecución del script.

<?php
// include_once
include_once 'funciones.php';
include_once 'funciones.php'; // Este segundo no se volverá a cargar

Require_once

¿Ya te lo imaginas no?

Bueno aún así te lo digo 😛

require_once hace lo mismo que require pero incluyendo solo una vez el archivo.

<?php
// require_once
require_once 'config.php';
require_once 'config.php'; // No se incluirá de nuevo

Si el archivo no existe, genera un error fatal (como require), pero además evita duplicados si ya fue cargado antes. Por tanto, si el archivo es importante y esencial y, no debe cargarse más de una vez, lo lógico es usar esta función.

Por cierto, después de todo no te has preguntado porqué algunas veces vemos esto:

require_once 'config.php';

o esto otro:

require_once ('config.php');

Va, seguro que sí. Seguro que leyendo el articulo has pensado… ¿y los paréntesis?

¿Con o sin paréntesis?

La verdad es que da igual, las dos formas son válidas y si tenemos algo de recorrido en PHP, unas veces lo habremos visto con paréntesis y otras sin paréntesis.

Independientemente de si los incluyes o no, funcionan igual y no hay diferencia en velocidad, en cómo se ejecuta, ni en el resultado, ni nada de eso.

¿Entonces por qué existen las dos formas?

Porque require, include, require_once e include_once no son funciones (aunque se parecen).

Son lo que PHP llama “instrucciones del lenguaje”. Por eso, los paréntesis no son necesarios. PHP simplemente permite ponerlos si tú quieres, pero no los necesita.

¿Y por qué algunos usuarios, programadores y… los usan con paréntesis?

Pues supongo porque visualmente para algunos queda mejor, pero vamos, que la forma oficial es la que hay en php.net, o sea:

require_once 'archivo.php';

Por cierto, guías como PSR-12 también los evitan para dejar claro que no se trata de una función, sino de una estructura del lenguaje.

Ahora bien, es importante mencionar que en algunos casos sí que se añaden, especialmente cuando el argumento es el resultado de una operación, por ejemplo:

require_once($ruta . '/config.php');

Pero una vez más (y perdona si te lio), da lo mismo. Con o sin paréntesis, es igual 🤷‍♂️

Para finalizar el artículo, recordemos que todos estos comandos sirven para incluir archivos en PHP y elegir el correcto marca la diferencia entre un código robusto o propenso a errores silenciosos.

Resumiendo:

• Usa require o require_once para archivos esenciales.
• Usa include o include_once para archivos opcionales o secundarios.

Y recuerda: si un archivo define funciones, clases o constantes, lo más recomendable es usar siempre *_once para evitar conflictos.

¡Nos vemos!

Sobre el autor