La arquitectura de Éclair

La arquitectura de Éclair se resume en una regla: hacer trabajar a PHP solo cuando hace falta. Esta lección sigue una petición de principio a fin, del servidor web a la caché estática, y muestra cómo se guardan los datos sin base de datos y qué clase hace cada cosa. Después podrás depurar, personalizar o alojar Éclair sabiendo cómo funciona por dentro.

¿Cómo atraviesa una petición la arquitectura de Éclair?

Todo parte de una constatación: la mayoría de las visitas piden una página que no ha cambiado. Por eso la arquitectura de Éclair la devuelve tal cual, sin leer ni un solo contenido. Este es el recorrido de una petición.

1. El servidor web. En Apache o LiteSpeed, el .htaccess envía a index.php cualquier dirección que no sea un archivo existente. Responde 404 para app/, data/, cache/, los archivos ocultos (salvo .well-known) y cualquier .php distinto de index.php, y transmite la cabecera Authorization al conector MCP.
2. La vía rápida de index.php. Para un GET o un HEAD, index.php lee cache/runtime.php y busca en cache/pages/ la página guardada con el md5 de la ruta. Si la encuentra, devuelve sus cabeceras guardadas, su ETag y X-Cache: HIT, o un 304 Not Modified si el navegador ya tiene esa versión.
3. El arranque. Si no, app/bootstrap.php comprueba la versión de PHP (8.1 como mínimo), carga eclair-config.php si existe, define ECLAIR_DATA y ECLAIR_DEBUG, registra la carga automática de las clases Eclair\… y llama a Eclair\App::run().
4. El enrutamiento. App::run() instala la gestión de errores y entrega la petición al módulo adecuado (tabla de abajo).
5. El renderizado. Site::handle() solo acepta GET y HEAD, impone una sola dirección por contenido (barra final, mayúsculas, index.php: redirección 301), sirve los archivos generados (robots.txt, sitemap.xml, llms.txt, feeds, versiones .md) y después busca el contenido. Cache::put() guarda cada página renderizada con el código 200.

La búsqueda, la página 404, la vista previa de la apariencia, el modo Visual y la administración nunca se guardan en caché. Para ver la vía rápida en acción, consulta dos veces la misma página:

# 1.ª llamada: la aplicación genera la página y la guarda
curl -sI https://exemple.fr/contact | grep -i -E 'etag|x-cache'
# ETag: "0745734655e7d523"

# 2.ª llamada: index.php la sirve desde cache/pages/, sin cargar la aplicación
curl -sI https://exemple.fr/contact | grep -i -E 'etag|x-cache'
# ETag: "0745734655e7d523"
# X-Cache: HIT

# El archivo de caché lleva el md5 de la ruta solicitada
php -r 'echo md5("/contact"), PHP_EOL;'   # 90609cfd31a32bdbd3d81843c57d356b

El almacenamiento en archivos planos: la clase Store

La arquitectura de Éclair prescinde de la base de datos: cada dato es un archivo data/<nom>.php que empieza por la línea <?php exit; ?>, seguida de JSON legible. Si se llama desde la web, no devuelve nada, incluso en un servidor que ignorara los .htaccess. Este es el principio de un archivo de menús real:

<?php exit; ?>
{
    "main": [
        {
            "type": "content",
            "id": "af59e5ba0a",
            "label": "",
            "url": ""
        }
    ]
}

Cuatro mecanismos hacen que este almacenamiento sea seguro, incluso en un hosting compartido muy cargado:

• Escritura atómica: Store::atomic() escribe un archivo temporal y después lo renombra, de modo que un lector nunca ve un archivo a medio escribir. Los archivos reciben los permisos 0600, y las carpetas de data/ y cache/, 0700.
• Ningún código inyectable: Store::write() codifica el JSON con JSON_HEX_TAG y JSON_HEX_AMP. Un < se convierte en \u003C: la secuencia <?php no puede aparecer en los datos.
• Bloqueo: Store::locked() pone un bloqueo exclusivo (flock) sobre data/.lock durante cada operación de lectura, modificación y escritura.
• Nombres controlados: Store::file() solo acepta minúsculas, números, guiones y barras. Es imposible salir de data/.

Todas las clases que escriben siguen este patrón, por ejemplo Redirects::add():

use Eclair\Store;

$menus = Store::read('menus', []);           // lectura, con un valor por defecto
Store::locked(function (): void {            // leer, modificar y escribir sin condiciones de carrera
    $list = Store::read('redirects', []);
    // … modificar $list …
    Store::write('redirects', $list);        // archivo temporal, 0600, renombrado
});

Los archivos de la carpeta data/

La última columna indica lo que conserva la copia de seguridad ZIP de la página Seguridad: los secretos y los datos temporales quedan fuera.

Las actualizaciones nunca tocan data/, que la constante ECLAIR_DATA puede incluso situar fuera de la carpeta pública.

Las clases principales de app/lib/

Todas las clases viven en el espacio de nombres Eclair\, un archivo por clase, sin framework ni Composer:

¿Por qué se vacía la caché con cada cambio?

Un título modificado aparece también en un menú, en una tarjeta de artículo o en las migas de pan. En lugar de adivinar esas dependencias, la arquitectura de Éclair lo vacía todo: Cache::purge() se ejecuta tras cada guardado de un contenido, de los ajustes, los menús, las categorías, los medios, un perfil o el CSS personalizado. Borra los archivos de cache/pages/ y reescribe cache/runtime.php; cada página se regenera en su primera visita.

<?php exit; ?>
{"on":true,"expires":0,"host":"exemple.fr","https":true}

index.php lee este pequeño archivo en cada petición:

• on: caché activa (Caché estática de páginas marcada y modo de depuración apagado);
• expires: fecha del próximo artículo programado; a partir de ella index.php ignora la caché, que vacía Cache::checkExpiry();
• host y https: host y protocolo oficiales, una vez verificada la dirección, para no saltarse nunca las redirecciones.

Cabeceras de seguridad y CSP

Security::headers() produce tres juegos de cabeceras: site, admin y text (sitemap, llms.txt, feeds). Dependen de los ajustes, nunca de la petición: nadie puede envenenar la caché con una cabecera falsificada. Estas son las de una página pública servida por HTTP, tomadas de Éclair 1.8:

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'sha256-…'; img-src 'self' data: https:; media-src 'self' https:; frame-src https://www.youtube-nocookie.com https://player.vimeo.com; connect-src 'self'; form-action 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=(), browsing-topics=()
Cross-Origin-Opener-Policy: same-origin

Theme::hash() calcula la huella sha256 sobre el CSS insertado en la página: solo se autoriza esa etiqueta <style>, no se permite ningún script en línea y el único script público es assets/site/site.js. Con HTTPS se añaden upgrade-insecure-requests y, si la opción HSTS está marcada, Strict-Transport-Security. La administración es aún más estricta: ningún estilo en línea, frame-ancestors 'none', noindex y Cache-Control: no-store, private.

Las traducciones

• Administración: cada texto se escribe en francés en el código, con t(). I18n::t() busca su traducción en app/lang/<langue>.json.gz, compilado por tools/i18n.php e indexado por la huella CRC32 del texto francés. Sin la extensión zlib, la administración se queda en francés.
• Sitio público: Theme::t('clé', $lang) lee el array Theme::STRINGS («Índice», «Lo esencial», «Leer en»…) en seis idiomas, y Theme::words() da las palabras de las direcciones (página, autor, búsqueda, tienda) en el idioma del sitio.

Para recordar

• En la arquitectura de Éclair, index.php sirve una página ya generada desde cache/pages/ sin cargar la aplicación: X-Cache: HIT lo demuestra.
• Lo demás pasa por app/bootstrap.php y después por App::run(), que lo encamina al instalador, la administración, el contacto, el MCP o el sitio.
• Los datos son archivos JSON detrás de <?php exit; ?>, escritos de forma atómica, con permisos 0600 y con bloqueo.
• La caché se vacía por completo con cada cambio y se reconstruye en la visita siguiente.
• Las cabeceras de seguridad solo dependen de los ajustes: la caché no puede envenenarse.

Para saber más

• Desarrollo local y pruebas: ejecutar Éclair en tu máquina y repetir sus 550 comprobaciones.
• Personalizar las plantillas del tema: actuar sobre el renderizado sin romper la CSP.
• Nginx, VPS, proxy y CDN: reproducir las reglas del .htaccess fuera de Apache.
• Seguridad avanzada y mantenimiento: integridad, copias de seguridad y actualizaciones.
• Documentación de PHP: flock() y rename(), en el corazón de las escrituras de Store.
• OWASP: hoja de referencia sobre la Content Security Policy, en inglés.

Todas las lecciones de la ruta