PHP Include

Introducción

Las sentencias include y require de PHP permiten insertar el contenido de un archivo PHP en otro antes de que el servidor lo ejecute. Esta es la base de la reutilización de código en PHP: en lugar de copiar una barra de navegación, una conexión a la base de datos o un conjunto de funciones auxiliares en cada página, lo escribes una vez en un archivo separado y lo incorporas donde sea necesario.

Este capítulo cubre las cuatro sentencias de inclusión (include, require, include_once, require_once), sus diferencias, el comportamiento de las variables y funciones incluidas, los errores comunes y las buenas prácticas que mantienen los proyectos grandes fáciles de mantener.

Por qué usar la inclusión de archivos

Dividir el código en archivos reutilizables ofrece tres ventajas concretas:

1. Menos repetición. Escribe una cabecera, pie de página o bloque de configuración una sola vez e inclúyelo en tantas páginas como necesites. Edítalo en un lugar y todas las páginas se actualizan.
2. Mantenimiento más fácil. Una corrección de errores o un cambio de diseño en el marcado compartido ocurre en un único archivo en lugar de en docenas de páginas.
3. Mejor organización. Dividir un script grande en archivos más pequeños con nombres descriptivos (header.php, db.php, functions.php) hace que el código sea más fácil de leer y navegar.

Las cuatro sentencias de inclusión

PHP ofrece cuatro sentencias. Todas copian el contenido de un archivo en el script actual, pero difieren en cómo manejan un archivo faltante y si permiten la re-inclusión.

Regla general: usa require (o require_once) para archivos sin los cuales la página no puede funcionar — una conexión a la base de datos o una definición de clase. Usa include para partes opcionales, como un bloque de anuncios o una barra lateral que es conveniente tener pero no crítica.

Sintaxis básica

<?php
// Include a file relative to the current script
include __DIR__ . '/header.php';

// Stop the page if a critical file is missing
require __DIR__ . '/db.php';

// Guarantee a file is loaded at most once
require_once __DIR__ . '/functions.php';
?>

__DIR__ es una constante mágica que se resuelve al directorio del archivo actual. Construir rutas a partir de ella hace que las inclusiones funcionen sin importar desde qué directorio se ejecute el script — consulta PHP Constants para más información sobre las constantes mágicas.

Por qué importa _once

Si incluyes dos veces un archivo que define una función o clase, PHP lanza un error fatal "Cannot redeclare" en el segundo pase. include_once y require_once registran qué archivos ya han sido cargados y omiten los duplicados en silencio, por lo que son la opción segura por defecto para cualquier archivo que declare funciones o clases.

<?php
require_once __DIR__ . '/functions.php'; // loads it
require_once __DIR__ . '/functions.php'; // skipped — no redeclare error
?>

Alcance de variables en archivos incluidos

Un archivo incluido se ejecuta en el alcance de la línea donde fue incluido. Las variables definidas antes del include están disponibles dentro del archivo incluido, y las variables que el archivo incluido define quedan disponibles después.

<?php
// config.php
$siteName = "My Site";
$year = 2026;

<?php
// index.php
include __DIR__ . '/config.php';
echo "Welcome to $siteName ($year)";
// Output: Welcome to My Site (2026)
?>

Sin embargo, dentro de una función, las variables del archivo incluido son locales a esa función. Esto suele confundir a los desarrolladores — un archivo de configuración incluido dentro de una función no filtrará sus variables al alcance global.

Retornar un valor desde un archivo incluido

Un archivo incluido puede usar return para devolver un valor, lo cual es muy útil para arreglos de configuración:

<?php
// settings.php
return [
    'debug'   => true,
    'timezone' => 'UTC',
];

<?php
// app.php
$config = include __DIR__ . '/settings.php';
echo $config['timezone']; // Output: UTC
?>

Manejar archivos faltantes con elegancia

Con include, un archivo faltante solo genera una advertencia, por lo que el resto de la página sigue renderizándose. Si un archivo es opcional, verifícalo primero:

<?php
$sidebar = __DIR__ . '/sidebar.php';

if (file_exists($sidebar)) {
    include $sidebar;
} else {
    echo "<!-- sidebar unavailable -->";
}
?>

Para archivos que la página realmente necesita, prefiere require para que el script falle de forma rápida y clara en lugar de producir una salida incorrecta.

Buenas prácticas

1. Usa require_once para código, include para salida opcional. Las definiciones de funciones y clases no deben cargarse dos veces; los fragmentos de interfaz opcionales pueden degradarse con elegancia.
2. Construye rutas desde __DIR__. Evita rutas relativas como include 'header.php', que dependen del directorio de trabajo actual y fallan de forma inesperada.
3. Nombra los archivos según su propósito. header.php, footer.php, db.php, auth.php — una sola mirada al nombre del archivo debe decirte qué contiene.
4. Mantén los archivos incluidos enfocados. Una responsabilidad por archivo los hace fáciles de reutilizar y razonar.
5. Nunca incluyas una ruta construida a partir de datos del usuario (ej. include $_GET['page']). Esto abre una vulnerabilidad de Inclusión de Archivos Local/Remota. En su lugar, usa una lista blanca de valores permitidos.

Conclusión

La familia include y require es la forma en que los proyectos PHP se mantienen DRY: el marcado compartido, la configuración y la lógica viven en archivos únicos y se incorporan a las páginas según se necesitan. Usa require/require_once cuando un archivo es obligatorio, include/include_once cuando es opcional, ancla siempre las rutas con __DIR__ y nunca incluyas una ruta controlada por el usuario. A continuación, consulta PHP Functions para organizar la lógica reutilizable que normalmente colocarás en archivos incluidos.

Diagrama

graph TD;
A[PHP Page]-->B[Included File];

Práctica