---
title: "Para desarrolladores"
description: "La guía para desarrolladores: arquitectura sin base de datos, pruebas, archivo de distribución, personalización del tema de Éclair CMS, Nginx y contribución."
url: "https://eclaircms.org/es/documentacion/desarrolladores"
lang: "es"
author: "Thierry Gustin"
published: "2026-10-30"
updated: "2026-11-01"
---

# Para desarrolladores

> **Lo esencial** — Éclair está escrito en PHP 8.1+ sin framework ni Composer: un controlador frontal que sirve la caché estática, un almacenamiento plano en archivos protegidos, clases sencillas y JavaScript nativo. El tema de Éclair CMS se personaliza en app/theme; 550 comprobaciones automáticas y una herramienta de compilación acompañan al código, con licencia MIT.

É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 479 KB, ninguna dependencia y páginas servidas en 0,7 ms en nuestras mediciones locales.

## ¿Qué contiene la carpeta eclair?

```text
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:

```bash
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](https://eclaircms.org/es/instalacion/local).

## ¿Cómo se lanzan las pruebas?

```bash
php tests/run.php          # 550 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?

```bash
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/`:

| Archivo | Función |
| --- | --- |
| `layout.php` | Plantilla principal: cabecera, menú, pie de página |
| `single.php` | Una página o un artículo |
| `list.php` | Blog, categorías, páginas de autor y búsqueda |
| `cards.php` | La cuadrícula de tarjetas de artículos |
| `404.php` | La página no encontrada |
| `theme.css` | Los estilos, minificados y luego insertados en cada página |

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».

> **Respeta la política de seguridad** — La Content-Security-Policy del sitio público prohíbe los scripts en línea: añade tu JavaScript en un archivo de `assets/`. En cuanto a los estilos, solo se permite la etiqueta `<style>` del tema, gracias a su huella SHA-256 calculada automáticamente; los atributos `style=""` están bloqueados.

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](https://eclaircms.org/es/documentacion/actualizaciones)). 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:

```nginx
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`, `session` y `zlib` son imprescindibles. Se recomiendan `gd` (imágenes WebP), `zip` (copias de seguridad), `curl` (IndexNow y asistente IA) 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](https://github.com/Jacckisback/eclair-cms): 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](https://lucide.dev), con licencia ISC. También puedes apoyar el proyecto en la página [Hacer una donación](https://eclaircms.org/es/donar).

## Preguntas de los desarrolladores

### ¿Hacen falta Composer o Node.js para desarrollar en Éclair?

No. Éclair no tiene ninguna dependencia: PHP 8.1 o superior basta para lanzar el sitio, las pruebas y la herramienta de compilación.

### ¿Puedo crear mi propio tema de Éclair CMS?

Sí: modifica las plantillas de app/theme y el archivo theme.css. Respeta la política de seguridad (ningún script en línea) y guarda una copia de tus archivos, que una actualización sustituiría.

### ¿Dónde se guardan los contenidos?

En data/content, un archivo por contenido, en formato JSON precedido de la línea de protección. data/index.php guarda un resumen para listar y enrutar con rapidez.

### ¿Cómo añado una traducción de la administración?

Las fuentes legibles están en la carpeta i18n del repositorio, con el texto francés como clave. tools/i18n.php las compila en archivos comprimidos, y php tools/build.php lo hace automáticamente.