include

La sentencia include de PHP

include incorpora el contenido de otro archivo PHP en el script actual y lo ejecuta en el punto donde aparece la sentencia. Conceptualmente, PHP copia el archivo incluido en su lugar, lo evalúa en el mismo ámbito y continúa. Así se evita repetir marcado y lógica compartidos — encabezados, pies de página, navegación, configuración y funciones reutilizables — en múltiples páginas.

Esta página cubre la sintaxis, cómo funciona el ámbito, qué devuelve include, en qué difiere de require y los errores comunes que hay que evitar.

Sintaxis

include 'filename.php';

La ruta puede ser relativa o absoluta. include es una construcción del lenguaje, no una función, por lo que los paréntesis son opcionales — tanto include 'file.php'; como include('file.php'); funcionan.

Cuando PHP ejecuta un include, busca el archivo en este orden: la ruta indicada (si es relativa, resuelta según el directorio de trabajo actual y la configuración de include_path), y luego el directorio del script en ejecución. Para que los includes funcionen correctamente independientemente de desde dónde se llame al script de entrada, anclarlos al archivo actual:

include __DIR__ . '/partials/header.php';

__DIR__ es el directorio del archivo que contiene la sentencia, por lo que el include se resuelve correctamente incluso cuando el script se ejecuta desde otro directorio.

Un ejemplo funcional

Dado que include opera sobre archivos separados, la forma más clara de verlo en acción es crear esos archivos en tiempo de ejecución. El fragmento siguiente escribe un pequeño parcial, lo incluye e imprime el resultado — es completamente ejecutable como un único script:

<?php
// Create a reusable partial on disk.
file_put_contents(__DIR__ . '/greeting.php', '<?php echo "Hello, " . $name . "!"; ?>');

// Variables defined here are visible inside the included file (shared scope).
$name = "Ada";

echo "Page top\n";
include __DIR__ . '/greeting.php';   // runs greeting.php here
echo "\nPage bottom\n";

// Output:
// Page top
// Hello, Ada!
// Page bottom

El archivo incluido puede leer $name porque include comparte el ámbito circundante. Esto es lo más importante que hay que entender sobre include: no es un sistema de módulos aislado. Las variables que existen antes del include están disponibles para el archivo incluido, y cualquier variable que defina el archivo incluido se filtra de vuelta al llamante.

Devolver un valor desde un archivo incluido

Un archivo incluido puede return un valor, que se convierte en el resultado de la expresión include. Esta es la forma idiomática de cargar configuración:

<?php
// Write a config file that returns an array.
file_put_contents(__DIR__ . '/config.php', '<?php return ["env" => "prod", "debug" => false];');

$config = include __DIR__ . '/config.php';

echo $config["env"];        // prod
echo "\n";
var_export($config["debug"]); // false

// Output:
// prod
// false

Si el archivo incluido no hace return, la expresión include evalúa a 1 en caso de éxito.

include vs require (y las variantes _once)

PHP tiene cuatro sentencias relacionadas. Todas incorporan un archivo; se diferencian en qué ocurre en caso de error y si se omiten los includes duplicados.

Reglas generales:

• Usa require para los archivos sin los cuales el script no puede ejecutarse (un archivo de configuración, una definición de clase, una conexión a base de datos). Fallar rápido con un error fatal es más seguro que continuar en un estado roto.
• Usa include para piezas opcionales, como un widget de barra lateral o un bloque de anuncios, donde un archivo faltante no debería derribar toda la página.
• Usa las variantes _once cuando volver a incluir un archivo causaría errores — más comúnmente cuando declara funciones o clases, ya que redeclararlas es un error fatal.

Errores comunes

• Confiar en datos del usuario en una ruta. Nunca pases datos de solicitud sin filtrar a include (por ejemplo include $_GET['page'] . '.php';). Abre la puerta a ataques de inclusión de archivos locales. En su lugar, valida contra una lista de archivos conocidos permitidos.
• Rutas relativas que fallan. Un include 'header.php'; simple depende del directorio de trabajo actual y puede fallar cuando el script se invoca desde otro lugar. Prefiere rutas ancladas a __DIR__.
• Redeclarar funciones o clases. Si un archivo que define funciones se incorpora dos veces mediante include simple, PHP lanza un error fatal "Cannot redeclare". Usa include_once para esos archivos.
• Asumir aislamiento. Dado que el ámbito es compartido, un archivo incluido puede sobreescribir tus variables. Mantén los includes enfocados y predecibles.

Por qué usar include

• Reutilización — define marcado o lógica compartidos una vez e incorpóralos en cada página que los necesite.
• Mantenibilidad — cambia la navegación en un parcial y todas las páginas se actualizan.
• Estructura — divide una aplicación grande en archivos pequeños y enfocados en lugar de un monolito.

Temas relacionados

• PHP require y require_once — las contrapartes que fallan en modo estricto.
• PHP include_once — incluir un archivo como máximo una vez.
• PHP Functions — lo que típicamente se coloca en archivos compartidos e incluidos.
• PHP File Handling — leer y escribir archivos en tiempo de ejecución.

Práctica