Pour les développeurs

Éclair est écrit en PHP 8.1 ou plus, sans framework ni Composer : des classes simples dans app/lib/, des vues PHP et du JavaScript natif. Ce guide explique son architecture, comment lancer les tests et préparer une archive, comment personnaliser le thème Éclair CMS sans casser la sécurité, et comment le servir avec Nginx.

Comment Éclair est-il construit ?

Trois idées font sa légèreté et sa rapidité :

1. Un contrôleur frontal qui sert le cache sans charger l’application. index.php cherche d’abord la page demandée dans cache/pages/ et l’envoie directement, avec ses en-têtes et son ETag (réponse 304 si rien n’a changé). L’application n’est chargée que pour une page pas encore en cache, l’administration ou l’installation.
2. Un stockage à plat, sans base de données. Chaque donnée est un fichier .php qui commence par <?php exit; ?>, suivi de JSON. Les écritures sont atomiques (fichier temporaire puis renommage), privées (0600) et faites sous verrou exclusif pour les lectures-modifications-écritures. data/index.php garde un résumé de tous les contenus pour lister et router vite.
3. Des blocs validés, puis rendus. Chaque bloc est validé et assaini par liste blanche, puis rendu en HTML, exporté en Markdown pour le GEO et analysé pour le SEO.

Résultat : une archive de 402 Ko, aucune dépendance, et des pages servies en 0,7 ms dans nos mesures locales.

Que contient le dossier eclair ?

eclair/                  ← à envoyer sur l’hébergement
├── index.php            contrôleur frontal (sert le cache sans charger l’application)
├── .htaccess            réécriture, protections, compression, cache navigateur
├── app/lib/             code (classes Eclair\…) : Content, Blocks, Seo, Analyzer, Media, Auth…
├── app/admin/views/     écrans de l’administration
├── app/theme/           gabarits du site public + theme.css (inséré dans chaque page)
├── app/lang/            traductions de l’administration (6 langues, JSON compressé)
├── assets/admin/        CSS et JavaScript de l’administration (aucune dépendance)
├── assets/site/site.js  le seul script public (2,4 Ko, 1,2 Ko compressé)
├── data/                contenus, réglages, comptes (créé à l’installation, jamais public)
├── cache/               pages générées
└── media/               images envoyées

Dans le dépôt, i18n/ contient les sources lisibles des traductions, tests/ les tests et tools/ le routeur de développement et l’outil de build.

Comment lancer Éclair en local ?

Depuis le dépôt, le serveur intégré de PHP suffit :

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

tools/router.php reproduit les règles du .htaccess. PHP_CLI_SERVER_WORKERS permet au site de s’appeler lui-même pour vérifier son adresse : avec un seul processus, la vérification échoue simplement et les redirections vers l’adresse officielle restent désactivées. Pour un test sans ligne de commande, voir Essayer Éclair sur ton ordinateur.

Comment lancer les tests ?

php tests/run.php          # 299 vérifications unitaires et HTTP
php tests/run.php --unit   # tests unitaires seulement

Les tests d’intégration démarrent un vrai serveur PHP et rejouent une grande partie des attaques de la revue de sécurité. tests/fake-ai.php simule les fournisseurs d’IA (Claude, ChatGPT, images) : l’assistant est testé sans clé ni dépense.

Comment préparer une archive distribuable ?

php tools/build.php

L’outil recompile les traductions depuis i18n/, calcule l’empreinte SHA-256 de chaque fichier dans app/manifest.php, la référence du contrôle d’intégrité, puis crée dist/eclair-cms-<version>.zip avec le fichier LISEZ-MOI, la licence et les mentions des tiers.

Comment personnaliser le thème Éclair CMS ?

Le site public est rendu par les gabarits de app/theme/ :

Les réglages d’apparence deviennent des variables CSS que ton thème peut réutiliser : --accent, --on-accent, --link, --link-dark, --font et --font-head. Le mode sombre se place entre les commentaires /*dark*/ et /*/dark*/ : Éclair retire ce bloc quand le réglage « Toujours clair » est choisi.

Garde une copie de tes gabarits : le contrôle d’intégrité les signalera comme modifiés, ce qui est normal, et une mise à jour d’Éclair les remplace (voir Mettre à jour). Le site eclaircms.org que tu lis est lui-même construit avec Éclair et un thème personnalisé : menu fixe, documentation avec menu latéral, pages précédente et suivante.

Comment servir Éclair avec Nginx ?

Éclair n’a pas besoin de .htaccess sous Nginx, mais il faut reproduire ces règles :

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

Pour que les réponses de l’assistant IA s’affichent au fil de l’eau, ajoute fastcgi_buffering off; dans le bloc PHP.

Quelles versions de PHP et quelles extensions faut-il ?

Éclair fonctionne de PHP 8.1 à 8.5 ; 8.3 est recommandé. Les extensions mbstring, json, dom et session sont indispensables. gd (images WebP), zip (sauvegardes), curl (IndexNow et assistant IA), zlib (administration traduite) et sodium ou openssl (clés de l’assistant) sont recommandées. L’assistant d’installation vérifie tout cela.

Comment contribuer à Éclair ?

Le code est public sur GitHub : signale un bug ou propose une idée dans les issues, ou envoie une pull request accompagnée de tests. Éclair est distribué sous licence MIT ; une partie des icônes de l’administration est dérivée de Lucide, sous licence ISC. Tu peux aussi soutenir le projet sur la page Faire un don.