Para desarrolladores

Éclair está escrito en PHP 8.1 o superior, sin framework ni Composer: clases sencillas en app/lib/, vistas PHP y JavaScript nativo. Esta guía explica su arquitectura, cómo lanzar las pruebas y preparar un archivo de distribución, cómo personalizar el tema de Éclair CMS sin romper la seguridad y cómo servirlo con Nginx.

¿Cómo está construido Éclair?

Tres ideas hacen que sea ligero y rápido:

1. Un controlador frontal que sirve la caché sin cargar la aplicación. index.php busca primero la página solicitada en cache/pages/ y la envía directamente, con sus cabeceras y su ETag (respuesta 304 si nada ha cambiado). La aplicación solo se carga para una página que aún no está en caché, para la administración o para la instalación.
2. Un almacenamiento plano, sin base de datos. Cada dato es un archivo .php que empieza con <?php exit; ?>, seguido de JSON. Las escrituras son atómicas (archivo temporal y después cambio de nombre), privadas (0600) y se hacen bajo bloqueo exclusivo para las operaciones de lectura, modificación y escritura. data/index.php guarda un resumen de todos los contenidos para listar y enrutar con rapidez.
3. Bloques validados y después renderizados. Cada bloque se valida y se sanea con una lista blanca, luego se renderiza en HTML, se exporta a Markdown para el GEO y se analiza para el SEO.

Resultado: un archivo de 440 KB, ninguna dependencia y páginas servidas en 0,7 ms en nuestras mediciones locales.

¿Qué contiene la carpeta eclair?

eclair/                  ← lo que se sube al hosting
├── index.php            controlador frontal (sirve la caché sin cargar la aplicación)
├── .htaccess            reescritura, protecciones, compresión, caché del navegador
├── app/lib/             código (clases Eclair\…): Content, Blocks, Seo, Analyzer, Media, Auth…
├── app/admin/views/     pantallas de la administración
├── app/theme/           plantillas del sitio público + theme.css (insertado en cada página)
├── app/lang/            traducciones de la administración (6 idiomas, JSON comprimido)
├── assets/admin/        CSS y JavaScript de la administración (sin dependencias)
├── assets/site/site.js  el único script público (2,4 KB, 1,2 KB comprimido)
├── data/                contenidos, ajustes, cuentas (se crea al instalar, nunca es público)
├── cache/               páginas generadas
└── media/               imágenes subidas

En el repositorio, i18n/ contiene las fuentes legibles de las traducciones, tests/ las pruebas y tools/ el enrutador de desarrollo y la herramienta de compilación.

¿Cómo se lanza Éclair en local?

Desde el repositorio, basta con el servidor integrado de PHP:

PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php

tools/router.php reproduce las reglas del .htaccess. PHP_CLI_SERVER_WORKERS permite que el sitio se llame a sí mismo para verificar su dirección: con un solo proceso, la verificación simplemente falla y las redirecciones a la dirección oficial siguen desactivadas. Para probarlo sin línea de comandos, consulta Probar Éclair en tu ordenador.

¿Cómo se lanzan las pruebas?

php tests/run.php          # 502 comprobaciones unitarias y HTTP
php tests/run.php --unit   # solo pruebas unitarias

Las pruebas de integración arrancan un servidor PHP real y reproducen buena parte de los ataques de la auditoría de seguridad. tests/fake-ai.php simula a los proveedores de IA (Claude, ChatGPT, imágenes): el asistente se prueba sin clave y sin gasto.

¿Cómo se prepara un archivo distribuible?

php tools/build.php

La herramienta vuelve a compilar las traducciones desde i18n/, calcula la huella SHA-256 de cada archivo en app/manifest.php, la referencia del control de integridad, y después crea dist/eclair-cms-<versión>.zip con el archivo LISEZ-MOI (léeme), la licencia y los avisos de terceros.

¿Cómo se personaliza el tema de Éclair CMS?

El sitio público se renderiza con las plantillas de app/theme/:

Los ajustes de apariencia se convierten en variables CSS que tu tema puede reutilizar: --accent, --on-accent, --link, --link-dark, --font y --font-head. El modo oscuro se coloca entre los comentarios /*dark*/ y /*/dark*/: Éclair elimina ese bloque cuando se elige el ajuste «Siempre claro».

Guarda una copia de tus plantillas: el control de integridad las señalará como modificadas, lo cual es normal, y una actualización de Éclair las sustituye (consulta Actualizar). El sitio eclaircms.org que estás leyendo está construido con Éclair y un tema personalizado: menú fijo, documentación con menú lateral, páginas anterior y siguiente.

¿Cómo servir Éclair con Nginx?

Éclair no necesita .htaccess con Nginx, pero hay que reproducir estas reglas:

location ~ ^/(app|data|cache)(/|$) { return 404; }
location ~ /\.(?!well-known/) { return 404; }
location ^~ /media/ {
    location ~* \.(php\d?|phtml|phar|s?html?|svgz?|xml|js)$ { return 404; }
    add_header X-Content-Type-Options nosniff;
    expires 1y;
}
location ~* \.(webp|avif|jpe?g|png|gif|ico|css|js|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }
location / { try_files $uri /index.php$is_args$args; }
location = /index.php {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}
location ~ \.php$ { return 404; }

Para que las respuestas del asistente IA se muestren a medida que se escriben, añade fastcgi_buffering off; en el bloque PHP.

¿Qué versiones de PHP y qué extensiones hacen falta?

Éclair funciona de PHP 8.1 a 8.5; se recomienda 8.3. Las extensiones mbstring, json, dom y session son imprescindibles. Se recomiendan gd (imágenes WebP), zip (copias de seguridad), curl (IndexNow y asistente IA), zlib (administración traducida) y sodium o openssl (claves del asistente). El asistente de instalación comprueba todo esto.

¿Cómo contribuir a Éclair?

El código es público en GitHub: comunica un error o propón una idea en los issues, o envía una pull request acompañada de pruebas. Éclair se distribuye con licencia MIT; parte de los iconos de la administración deriva de Lucide, con licencia ISC. También puedes apoyar el proyecto en la página Hacer una donación.