Organizar tu código: include, estructura, constantes

Divide tu sitio en archivos reutilizables con include y require, una estructura de proyecto clara y constantes centralizadas.

7 min · 3 preguntas

En cuanto tu sitio crece más allá de dos páginas, duplicar el encabezado, el pie de página y las funciones en cada archivo se vuelve inmanejable. PHP ofrece cuatro instrucciones de inclusión: include, require, y sus variantes include_once / require_once. Todas insertan el contenido de un archivo en el punto de la llamada; la diferencia está en el manejo de errores y las inclusiones repetidas. Las variantes _once llevan un registro de los archivos ya cargados y los incluyen una sola vez - esencial para los archivos de funciones, que no se pueden redeclarar.

<?php

declare(strict_types=1);

function e(string $value): string
{
    return htmlspecialchars($value, ENT_QUOTES);
}

function formatPrice(float $amount): string
{
    return number_format($amount, 2, '.', ',') . ' €';
}

Una estructura de proyecto clara vale por mil comentarios. Una convención habitual: public/ contiene las páginas servidas al navegador (es la única carpeta expuesta), src/ reúne la configuración y las funciones, templates/ contiene fragmentos de página (header.php, footer.php). El servidor de desarrollo integrado de PHP se inicia apuntándolo a public/.

mkdir -p my-site/public my-site/src
mkdir -p my-site/templates
cd my-site
php -S localhost:8000 -t public

Los valores fijos del proyecto (nombre del sitio, rutas, ajustes) merecen constantes en lugar de variables: no se pueden sobrescribir por accidente. const se resuelve en tiempo de compilación, define() en tiempo de ejecución; en la práctica, prefiere const en tus archivos de configuración. Para las rutas, antepón siempre __DIR__, la carpeta del archivo actual: tus inclusiones funcionarán sin importar desde dónde se inicie el script.

<?php

declare(strict_types=1);

const SITE_NAME = 'La Bonne Pizza';
const ITEMS_PER_PAGE = 12;
const UPLOAD_DIR = __DIR__ . '/../public/uploads';

define('BASE_URL', 'http://localhost:8000');

Cada página se convierte entonces en un breve ensamblaje: carga la configuración y las funciones con require, luego incluye las plantillas alrededor del contenido específico.

<?php
require __DIR__ . '/../src/config.php';
require_once __DIR__ . '/../src/functions.php';

$pageTitle = SITE_NAME . ' - Home';
include __DIR__ . '/../templates/header.php';
?>
<main>
  <h1><?= e($pageTitle) ?></h1>
  <p>Pizza of the day: <?= formatPrice(9.5) ?></p>
</main>
<?php include __DIR__ . '/../templates/footer.php'; ?>

Prueba de conocimientos

Comprueba que has retenido los puntos clave de esta lección.

1. ¿Cuál es la diferencia entre include y require?
   • include es más rápido que require
   • require solo funciona con rutas absolutas
   • require detiene el script con un error fatal si falta el archivo, include emite un aviso y continúa
   • Ninguna, son dos alias
2. ¿Para qué sirve require_once?
   • Para garantizar que un archivo se incluya una sola vez, incluso si varios archivos lo solicitan
   • Para incluir un archivo solo en producción
   • Para incluir un archivo sin ejecutar su código PHP
3. ¿Por qué anteponer __DIR__ a las rutas de inclusión?
   • Es obligatorio desde PHP 8
   • La ruta se vuelve relativa al archivo actual y ya no depende de la carpeta desde la que se inicia el script
   • Habilita una caché de los archivos incluidos