Per sviluppatori

Éclair è scritto in PHP 8.1 o successivo, senza framework né Composer: classi semplici in app/lib/, viste PHP e JavaScript nativo. Questa guida spiega la sua architettura, come lanciare i test e preparare un archivio, come personalizzare il tema di Éclair CMS senza compromettere la sicurezza e come servirlo con Nginx.

Come è costruito Éclair?

Tre idee ne fanno la leggerezza e la rapidità:

1. Un front controller che serve la cache senza caricare l’applicazione. index.php cerca prima la pagina richiesta in cache/pages/ e la invia direttamente, con i suoi header e il suo ETag (risposta 304 se nulla è cambiato). L’applicazione viene caricata solo per una pagina non ancora in cache, per l’amministrazione o per l’installazione.
2. Uno storage a file, senza database. Ogni dato è un file .php che inizia con <?php exit; ?>, seguito da JSON. Le scritture sono atomiche (file temporaneo, poi rinomina), private (0600) ed eseguite con un lock esclusivo per le operazioni di lettura-modifica-scrittura. data/index.php conserva un riepilogo di tutti i contenuti per elencarli e instradarli rapidamente.
3. Blocchi convalidati, poi renderizzati. Ogni blocco viene convalidato e sanificato tramite lista bianca, poi renderizzato in HTML, esportato in Markdown per la GEO e analizzato per la SEO.

Il risultato: un archivio di 440 KB, nessuna dipendenza e pagine servite in 0,7 ms nelle nostre misurazioni locali.

Cosa contiene la cartella eclair?

eclair/                  ← da caricare sull’hosting
├── index.php            front controller (serve la cache senza caricare l’applicazione)
├── .htaccess            riscrittura, protezioni, compressione, cache del browser
├── app/lib/             codice (classi Eclair\…): Content, Blocks, Seo, Analyzer, Media, Auth…
├── app/admin/views/     schermate dell’amministrazione
├── app/theme/           template del sito pubblico + theme.css (inserito in ogni pagina)
├── app/lang/            traduzioni dell’amministrazione (6 lingue, JSON compresso)
├── assets/admin/        CSS e JavaScript dell’amministrazione (nessuna dipendenza)
├── assets/site/site.js  l’unico script pubblico (2,4 KB, 1,2 KB compresso)
├── data/                contenuti, impostazioni, account (creato all’installazione, mai pubblico)
├── cache/               pagine generate
└── media/               immagini caricate

Nel repository, i18n/ contiene i sorgenti leggibili delle traduzioni, tests/ i test e tools/ il router di sviluppo e lo strumento di build.

Come eseguire Éclair in locale?

Dal repository, basta il server integrato di PHP:

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

tools/router.php riproduce le regole del .htaccess. PHP_CLI_SERVER_WORKERS permette al sito di chiamare se stesso per verificare il proprio indirizzo: con un solo processo, la verifica semplicemente fallisce e i reindirizzamenti all’indirizzo ufficiale restano disattivati. Per una prova senza riga di comando, vedi Provare Éclair sul tuo computer.

Come eseguire i test?

php tests/run.php          # 502 verifiche unitarie e HTTP
php tests/run.php --unit   # solo test unitari

I test di integrazione avviano un vero server PHP e ripetono gran parte degli attacchi dell’audit di sicurezza. tests/fake-ai.php simula i fornitori di IA (Claude, ChatGPT, immagini): l’assistente viene testato senza chiavi né spese.

Come preparare un archivio distribuibile?

php tools/build.php

Lo strumento ricompila le traduzioni da i18n/, calcola l’impronta SHA-256 di ogni file in app/manifest.php, il riferimento del controllo di integrità, poi crea dist/eclair-cms-<versione>.zip con il file LISEZ-MOI, la licenza e le note sui componenti di terzi.

Come personalizzare il tema di Éclair CMS?

Il sito pubblico viene renderizzato dai template di app/theme/:

Le impostazioni di aspetto diventano variabili CSS che il tuo tema può riutilizzare: --accent, --on-accent, --link, --link-dark, --font e --font-head. La modalità scura si colloca tra i commenti /*dark*/ e /*/dark*/: Éclair rimuove questo blocco quando è scelta l’impostazione «Sempre chiaro».

Conserva una copia dei tuoi template: il controllo di integrità li segnalerà come modificati, ed è normale, e un aggiornamento di Éclair li sostituisce (vedi Aggiornare). Il sito eclaircms.org che stai leggendo è esso stesso costruito con Éclair e un tema personalizzato: menu fisso, documentazione con menu laterale, pagine precedente e successiva.

Come servire Éclair con Nginx?

Con Nginx, Éclair non ha bisogno di .htaccess, ma bisogna riprodurre queste regole:

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; }

Perché le risposte dell’assistente IA compaiano man mano che vengono scritte, aggiungi fastcgi_buffering off; nel blocco PHP.

Quali versioni di PHP e quali estensioni servono?

Éclair funziona da PHP 8.1 a 8.5; si consiglia l’8.3. Le estensioni mbstring, json, dom e session sono indispensabili. Sono consigliate gd (immagini WebP), zip (backup), curl (IndexNow e assistente IA), zlib (amministrazione tradotta) e sodium o openssl (chiavi dell’assistente). La procedura guidata di installazione verifica tutto questo.

Come contribuire a Éclair?

Il codice è pubblico su GitHub: segnala un bug o proponi un’idea nelle issue, oppure invia una pull request accompagnata da test. Éclair è distribuito con licenza MIT; una parte delle icone dell’amministrazione deriva da Lucide, con licenza ISC. Puoi anche sostenere il progetto dalla pagina Dona.