Développement local et tests

Le développement local d'Éclair ne demande ni Composer, ni base de données, ni conteneur : PHP 8.1 ou plus suffit. Dans cette leçon, tu lances le site sur ta machine, tu fais tourner les 550 vérifications automatiques, tu construis l'archive distribuable, tu mesures avec Lighthouse et tu testes le connecteur MCP, avant de toucher à un site en ligne.

Lancer Éclair en développement local

git clone https://github.com/Jacckisback/eclair-cms.git
cd eclair-cms
PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php

L'option -t eclair fait du dossier eclair/ la racine du site, comme le dossier public d'un hébergement. Le script tools/router.php reproduit les règles du .htaccess : 404 pour app/, data/, cache/, les fichiers cachés et tout .php autre qu'index.php, aucun script ni page dans media/. Il sert tels quels les fichiers existants et envoie tout le reste à index.php.

Pourquoi PHP_CLI_SERVER_WORKERS=4 ? Pour vérifier son adresse, le site s'appelle lui-même sur /__eclair/ping. Avec un seul processus, le serveur intégré est occupé par la requête en cours et ne peut pas répondre : la vérification échoue, et les redirections vers l'adresse officielle restent coupées. PHP ne gère pas plusieurs processus sous Windows : passe par WSL, ou accepte une adresse non vérifiée en local.

Ouvre ensuite http://localhost:8000 : l'assistant d'installation démarre, avec la même fenêtre de 2 heures qu'en ligne. Garde toujours la même adresse (localhost ou 127.0.0.1) : c'est celle que l'installation enregistre. Tes données locales vont dans eclair/data/, que Git ignore, tout comme le cache, les images envoyées et eclair-config.php.

Comment lancer les tests d'Éclair ?

php tests/run.php                  # unitaires + intégration HTTP
# ✅ 550 vérifications réussies

php tests/run.php --unit           # unitaires seulement, en quelques secondes
# ✅ 241 vérifications réussies

# Même batterie de tests sur une archive décompressée
ECLAIR_TEST_ROOT=/tmp/archive/eclair php tests/run.php

Les tests ne touchent pas à ton site de développement local : les données des tests unitaires vont dans le dossier temporaire du système. Chaque test HTTP copie eclair/ dans ce même dossier, vide ses données, lance php -S sur un port au hasard avec quatre processus et tools/router.php, installe un site, puis rejoue ses scénarios avec curl. En cas d'échec, la liste des vérifications ratées s'affiche et la commande se termine avec le code 1 : elle s'intègre telle quelle à une chaîne d'intégration continue.

Développer l'assistant IA sans clé ni dépense

tests/fake-ai.php imite les API d'Anthropic, d'OpenAI, de FLUX et d'Ideogram. Les tests le lancent sur un port local et écrivent dans leur copie un eclair-config.php qui définit ECLAIR_AI_ENDPOINTS. Tu peux reproduire ce montage pour travailler sur l'interface de l'assistant :

# Terminal 1 : faux fournisseurs (journal des requêtes dans /tmp/fake-ai/log.jsonl)
mkdir -p /tmp/fake-ai
FAKE_AI_DIR=/tmp/fake-ai php -S 127.0.0.1:9999 tests/fake-ai.php

<?php
// eclair/eclair-config.php : l'assistant parle aux faux fournisseurs
defined('ECLAIR') || exit;
define('ECLAIR_AI_ENDPOINTS', ['anthropic' => 'http://127.0.0.1:9999', 'openai' => 'http://127.0.0.1:9999']);

Le faux serveur n'accepte que ses clés de test, comme sk-ant-test-0123456789, et réagit à un mot-clé placé dans ta demande : ARTICLE (image puis brouillon), EQUIPE (ajout d'un membre) ou PIEGE (texte malveillant), entre autres.

Construire l'archive distribuable

php tools/build.php
# ✓ Traductions : 6 langues compilées (eclair/app/lang)
# ✓ Empreintes : 126 fichiers (app/manifest.php)
# ✓ Archive : …/dist/eclair-cms-1.8.0.zip (479 Ko, 981 991 octets une fois décompressée)

La version vient de la constante ECLAIR_VERSION d'eclair/index.php. Le script recompile les traductions, calcule l'empreinte SHA-256 de chaque fichier (ses 128 premiers bits) dans app/manifest.php, base du contrôle d'intégrité, puis crée dist/eclair-cms-<version>.zip. Dans l'archive, le PHP est compacté avec php -w, les vues de l'administration sont compressées (.php.gz, lues par zlib) et le JavaScript et le CSS de l'administration sont allégés. Le rendu public reste identique à l'octet près. Le contenu de data/, cache/ et media/ et ton eclair-config.php sont exclus, tandis que LISEZ-MOI.txt, LICENSE.txt et THIRD-PARTY-NOTICES.txt s'ajoutent. Sans l'extension zip, aucune archive n'est créée.

Capturer le rendu et mesurer avec Lighthouse

npm install -g lighthouse              # Node.js 22 ou plus
php tools/capture.php                  # empreintes du rendu → tests/fixtures/public-<version>.json
php tools/capture.php --lighthouse     # Lighthouse mobile → tests/fixtures/lighthouse-<version>.json

tools/capture.php sert les quatre sites de référence de tests/fixtures/sites/ (blog, business, freelance, landing) et enregistre l'empreinte de chaque page, pour un visiteur puis avec une session d'administration, le HTML de chaque bloc et les fichiers CSS et JS publics. tests/run.php compare le rendu courant à public-1.6.0.json : une nouvelle version ne doit pas changer un octet du site public. L'option --reinstall recrée les sites de départ, donc de nouvelles empreintes : les références existantes ne valent plus.

Avec --lighthouse, l'outil mesure en mobile l'accueil et un article du site « business », la page « landing », puis l'accueil habillé de quatre directions artistiques, en gardant la médiane de trois passages. Les variables LIGHTHOUSE et CHROME_PATH désignent la commande et le navigateur. Pour Éclair 1.8, chaque page mesurée obtient 100 dans les quatre catégories, avec un LCP de 779 à 885 ms, un CLS de 0 et un TBT de 0 à 17 ms.

Mode débogage et eclair-config.php

Copie eclair/eclair-config.exemple.php sous le nom eclair-config.php, à côté d'index.php, et n'y garde que les lignes utiles. Voici le modèle, complété de la constante ECLAIR_SECRET :

<?php
defined('ECLAIR') || exit;

// Détail des erreurs et cache statique coupé : le temps de résoudre un problème.
define('ECLAIR_DEBUG', true);

// Données hors du dossier public (déplace d'abord le dossier « data »).
// define('ECLAIR_DATA', '/home/moncompte/eclair-data');

// Secret supplémentaire pour le coffre des clés d'API, avant de les enregistrer.
// define('ECLAIR_SECRET', 'une-longue-phrase-secrète');

Sans mode débogage, une erreur affiche « Oups, un court-circuit » avec une référence de 8 caractères. Le détail est consigné dans data/logs/errors.php et visible sur la page Sécurité, rubrique Dernières erreurs techniques : c'est la bonne méthode sur un site en ligne, où ECLAIR_DEBUG montrerait tes erreurs aux visiteurs.

Tester le connecteur MCP avec MCP Inspector

1. Dans l'administration locale, ouvre Réglages › Assistant IA, active Autoriser les connexions MCP et enregistre. Un avertissement rappelle que Claude et ChatGPT exigent une adresse en https : l'Inspector, lui, accepte ton adresse locale.
2. Vérifie la découverte OAuth et le refus sans jeton avec les deux premières commandes ci-dessous.
3. Lance l'Inspector avec l'adresse du connecteur (troisième commande).
4. Connecte-toi depuis l'Inspector : il lit la découverte, s'enregistre (Éclair accepte les adresses de retour en http://localhost, 127.0.0.1 ou [::1]), puis ouvre la page d'accord d'Éclair. Identifie-toi et clique sur Autoriser.
5. Liste les outils : get_site, search_content, get_content et find_media en lecture ; create_draft et update_content en écriture, limités à 60 par heure et par connexion.

# Découverte : ressource protégée et serveur d'autorisation
curl -s http://localhost:8000/.well-known/oauth-protected-resource

# Sans jeton : refus 401 qui pointe vers la découverte
curl -si -X POST http://localhost:8000/_eclair/mcp | grep -i www-authenticate
# WWW-Authenticate: Bearer resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource"

# MCP Inspector, interface web
npx @modelcontextprotocol/inspector --server-url http://localhost:8000/_eclair/mcp --transport http

Le connecteur d'Éclair 1.8 annonce les versions 2025-11-25, 2025-06-18 et 2025-03-26 du protocole. Pour un test scriptable, la même commande avec --cli et --method tools/list liste les outils dans le terminal.

À retenir

• Le développement local d'Éclair tient en une commande : PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php.
• php tests/run.php rejoue 550 vérifications sur des copies, sans toucher à ton site ; --unit se limite aux 241 tests unitaires.
• php tools/build.php produit l'archive et réécrit app/manifest.php, base du contrôle d'intégrité.
• eclair-config.php porte les réglages avancés ; ECLAIR_DEBUG ne reste actif que le temps d'un diagnostic.
• MCP Inspector teste le connecteur en local, OAuth compris, avant Claude ou ChatGPT.

Pour aller plus loin

• L'architecture d'Éclair : ce que tes tests exercent, requête par requête.
• Personnaliser les gabarits du thème : modifier le rendu, puis le vérifier avec ces outils.
• Comprendre le connecteur MCP : les six outils et ce que l'IA ne peut pas faire.
• Performance : garder 100 sur 100 : lire et interpréter une mesure Lighthouse.
• PHP : le serveur web interne et ses scripts routeurs.
• Model Context Protocol : documentation de MCP Inspector.

Toutes les leçons du parcours