---
title: "Per sviluppatori"
description: "La guida per sviluppatori: architettura senza database, test, archivio, personalizzazione del tema di Éclair CMS, configurazione di Nginx e contributi."
url: "https://eclaircms.org/it/documentazione/sviluppatori"
lang: "it"
author: "Thierry Gustin"
published: "2026-10-30"
updated: "2026-11-01"
---

# Per sviluppatori

> **In breve** — Éclair è scritto in PHP 8.1+ senza framework né Composer: un front controller che serve la cache statica, uno storage a file protetti, classi semplici e JavaScript nativo. Il tema di Éclair CMS si personalizza in app/theme; 550 verifiche automatiche e uno strumento di build accompagnano il codice, con licenza MIT.

É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 479 KB, nessuna dipendenza e pagine servite in 0,7 ms nelle nostre misurazioni locali.

## Cosa contiene la cartella eclair?

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

```bash
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](https://eclaircms.org/it/installazione/locale).

## Come eseguire i test?

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

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

| File | Ruolo |
| --- | --- |
| `layout.php` | Template principale: intestazione, menu, piè di pagina |
| `single.php` | Una pagina o un articolo |
| `list.php` | Blog, categorie, pagine autore e ricerca |
| `cards.php` | La griglia di card degli articoli |
| `404.php` | La pagina non trovata |
| `theme.css` | Gli stili, minificati poi inseriti in ogni pagina |

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

> **Rispetta la politica di sicurezza** — La Content-Security-Policy del sito pubblico vieta gli script in linea: aggiungi il tuo JavaScript in un file di `assets/`. Per gli stili, è autorizzato solo il tag `<style>` del tema, grazie alla sua impronta SHA-256 calcolata automaticamente; gli attributi `style=""` sono bloccati.

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](https://eclaircms.org/it/documentazione/aggiornamenti)). 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:

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

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`, `session` e `zlib` sono indispensabili. Sono consigliate `gd` (immagini WebP), `zip` (backup), `curl` (IndexNow e assistente IA) e `sodium` o `openssl` (chiavi dell’assistente). La procedura guidata di installazione verifica tutto questo.

## Come contribuire a Éclair?

Il codice è pubblico su [GitHub](https://github.com/Jacckisback/eclair-cms): 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](https://lucide.dev), con licenza ISC. Puoi anche sostenere il progetto dalla pagina [Dona](https://eclaircms.org/it/dona).

## Domande degli sviluppatori

### Servono Composer o Node.js per sviluppare su Éclair?

No. Éclair non ha alcuna dipendenza: PHP 8.1 o successivo basta per avviare il sito, i test e lo strumento di build.

### Posso creare un mio tema per Éclair CMS?

Sì: modifica i template di app/theme e il file theme.css. Rispetta la politica di sicurezza (nessuno script in linea) e conserva una copia dei tuoi file, che un aggiornamento sostituirebbe.

### Dove sono archiviati i contenuti?

In data/content, un file per contenuto, in formato JSON preceduto dalla riga di protezione. data/index.php ne conserva un riepilogo per elencarli e instradarli rapidamente.

### Come aggiungo una traduzione dell’amministrazione?

I sorgenti leggibili sono nella cartella i18n del repository, con il testo francese a fare da chiave. tools/i18n.php li compila in file compressi, e php tools/build.php lo fa automaticamente.