---
title: "Pour les développeurs"
description: "Le guide développeur : architecture sans base de données, tests, archive, personnalisation du thème Éclair CMS, configuration Nginx et contribution."
url: "https://eclaircms.org/documentation/developpeurs"
lang: "fr"
author: "Thierry Gustin"
published: "2026-10-30"
updated: "2026-10-30"
---

# Pour les développeurs

> **L’essentiel** — Éclair est écrit en PHP 8.1+ sans framework ni Composer : un contrôleur frontal qui sert le cache statique, un stockage à plat en fichiers protégés, des classes simples et du JavaScript natif. Le thème Éclair CMS se personnalise dans app/theme ; 299 vérifications automatiques et un outil de build accompagnent le code, sous licence MIT.

É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 ?

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

```bash
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](https://eclaircms.org/installation/ordinateur).

## Comment lancer les tests ?

```bash
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 ?

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

| Fichier | Rôle |
| --- | --- |
| `layout.php` | Gabarit principal : en-tête, menu, pied de page |
| `single.php` | Une page ou un article |
| `list.php` | Blog, catégories, pages auteur et recherche |
| `cards.php` | La grille de cartes d’articles |
| `404.php` | La page introuvable |
| `theme.css` | Les styles, minifiés puis insérés dans chaque page |

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.

> **Respecte la politique de sécurité** — La Content-Security-Policy du site public interdit les scripts en ligne : ajoute ton JavaScript dans un fichier de `assets/`. Côté styles, seule la balise `<style>` du thème est autorisée, grâce à son empreinte SHA-256 calculée automatiquement ; les attributs `style=""` sont bloqués.

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](https://eclaircms.org/documentation/mise-a-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 :

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

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](https://github.com/Jacckisback/eclair-cms) : 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](https://lucide.dev), sous licence ISC. Tu peux aussi soutenir le projet sur la page [Faire un don](https://eclaircms.org/faire-un-don).

## Questions des développeurs

### Faut-il Composer ou Node.js pour développer sur Éclair ?

Non. Éclair n’a aucune dépendance : PHP 8.1 ou plus suffit pour lancer le site, les tests et l’outil de build.

### Puis-je créer mon propre thème Éclair CMS ?

Oui : modifie les gabarits de app/theme et le fichier theme.css. Respecte la politique de sécurité (pas de script en ligne) et garde une copie de tes fichiers, qu’une mise à jour remplacerait.

### Où sont stockés les contenus ?

Dans data/content, un fichier par contenu, au format JSON précédé de la ligne de protection. data/index.php en garde un résumé pour lister et router rapidement.

### Comment ajouter une traduction de l’administration ?

Les sources lisibles sont dans le dossier i18n du dépôt, le texte français servant de clé. tools/i18n.php les compile en fichiers compressés, et php tools/build.php le fait automatiquement.