Observabilité, diagnostic et CLI
Comment voir ce qui se passe sur une stack où les erreurs ne peuvent pas être affichées.
1. La règle de base : display_errors = 0, toujours
ff/error_handling.php centralise la gestion des erreurs et force display_errors à 0. Ce n'est pas une préférence, c'est une contrainte structurelle : un warning affiché
- corrompt la sortie binaire des images servies par
showfiles, - casse les en-têtes d'une réponse JSON,
- et de toute façon montre chemins et requêtes à l'utilisateur.
Les dépréciations « propriétés dynamiques » de PHP 8.2 sont réduites au silence, pas corrigées : il y en a des milliers dans une base de code de 14 400 fichiers, et les corriger serait une réécriture.
1bis. Ce que voit le visiteur : le document d'erreur et la maintenance
Un 404 décidé par le routeur, un 404/403 d'Apache (ErrorDocument → cm/error.php) et une erreur fatale aboutissent dans cms_error_document() (cm/errori.php) : du JSON pour les appels XHR et API, sinon la page cm/extras/404.html ou cm/extras/500.html (une page de marque dans conf/cm/extras/ l'emporte), avec une référence à retrouver dans le journal. La page ne passe pas par ffTemplate, parce qu'elle doit s'afficher même avec le framework cassé : les placeholders ({titolo}, {sommario}, {url_home}, …, en plus de {ID_richiesta}, {URL_richiesta} et {anno}) sont remplis par cms_error_testi() avec strtr().
Les textes sont en quatre langues dans cm/errori.php, parce qu'ici la base de données peut manquer. cms_error_lingua() choisit : la langue décidée par le noyau (LANGUAGE_INSET_TINY), s'il y en a une ; le préfixe de l'adresse (/en/…) ; le navigateur (Accept-Language) ; l'italien. Une langue active mais sans textes reçoit l'anglais. L'accueil et la connexion pointent vers la même langue (/fr, /fr/login).
La page de maintenance (cm/maintenance.php, quand le fichier .maintenance existe) tourne avant le config et le noyau, elle choisit donc la langue seulement d'après l'adresse et le navigateur, avec la même fonction. Elle se termine par exit : jusqu'à la 3.0.3 ce n'était pas le cas, et après la page 503 index.php démarrait quand même le CMS, exactement ce que la maintenance doit éviter pendant une mise à jour.
2. Débogage à la demande : ?__debug__
https://site/page?__debug__
ff/error_handling.php:51 réactive display_errors pour cette seule requête. C'est la manière prévue de regarder une erreur dans un environnement où display_errors doit rester désactivé.
Qui peut l'utiliser. cm/livello-errori.php, le premier fichier inclus par chaque point d'entrée (API comprise), retire __debug__ et __query__ de la requête pour ceux qui ne peuvent pas les demander, ainsi le reste du CMS ne les voit pas. Peuvent les demander :
- la ligne de commande ;
- le serveur qui l'accorde exprès :
SetEnv JC_DEBUG_ALLOWED 1dans le.htaccess(ou dans le vhost), ou la variable d'environnementJC_DEBUG_ALLOWED=1pour le serveur de PHP ; - une copie de travail
.localvue depuis la machine elle-même (REMOTE_ADDRde loopback).
Sur staging et production, donc, rien ne s'allume par défaut : pour regarder une erreur là-bas on met la SetEnv le temps nécessaire, puis on l'enlève.
Dans le code, deux prédicats pilotent le comportement :
ffErrorHandler::logEnabled(); // écrit dans le log
ffErrorHandler::hideEnabled(); // masque à l'écran — false quand __debug__ est présent
Et ffErrorHandler::raise($message, E_USER_ERROR, $context, $variables) est disponible pour lever une erreur applicative qui passe par la même chaîne (avec stack trace, constantes compactées et affichage structuré).
⚠️
?__debug__est utile et doit être traité comme une fonction de diagnostic en production : il expose chemins, requêtes et variables. Jusqu'à la 1.6.2 n'importe qui pouvait le demander ; depuis la 1.7.0 il est fermé par défaut (voir plus haut), etJC_DEBUG_ALLOWEDne doit pas rester allumé en production.
3. Logs
| Outil | Où il écrit |
|---|---|
Cache::log($data, $filename) | fichier de log dans le dossier de cache (cache/logs/) ; c'est celui qu'utilise le bus des services pour request_error_js / request_error_css. cache/logs/ est fermé au navigateur par le .htaccess : jusqu'à la 3.1.0 les logs de la journée se téléchargeaient (14 §3) |
error_log() de PHP | log du serveur web — le repli qui fonctionne toujours |
vendor/hcore/logs/ | abstraction avec un service splunk |
library/gallery/system/trace.php | suivi des visites (system_trace, system_write_trace), avec reconnaissance des crawlers (system_trace_isCrawler) et profil du visiteur |
vendor/hcore/stats/ | statistiques : action, page, trace, user, visitor |
Pour un nouveau sous-système, le modèle éprouvé est un fichier de log dédié, activé par défaut et désactivable par configuration, avec une ligne par événement et un résultat reconnaissable. Il sert surtout pour les webhooks et les jobs : sans lui, le tri est impossible (03 §2).
4. Sentry
Initialisé dans hook.php juste après la définition du domaine :
require_once(__DIR__ . "/library/sentry/bootstrap.php");
cms_sentry_init();
- piloté par
SENTRY_DSNdans la configuration (l'assistant le demande, étape Services) ; - défensif : ne fait rien si le DSN manque ou si la bibliothèque n'est pas là ;
- le domaine ne sert que d'étiquette d'environnement (
production/staging).
5. Profiling et diagnostic
| Outil | Quoi |
|---|---|
conf/profiling/{admin,data-entry,user}.xml | profils de profiling par rôle |
MOD_SEC_PROFILING (hook.php) | interrupteur, false par défaut ; un site le change dans le config |
conf/gallery/job/diagnostic/ | vérifie cache, dictionnaire, config, uploads, miniatures et écrit le résultat comme notification de backend |
library/gallery/common/check_system.php, check_fs.php | vérifications système et filesystem |
library/gallery/job.php → get_check_fs() | permissions et tailles de l'arborescence des fichiers |
6. Exécution en ligne de commande
Elle sert aux workers, aux scripts de maintenance, au diagnostic et aux tests automatiques. En CLI la stack se comporte différemment de trois façons, toutes capables de produire un fatal invisible depuis le web :
- Les helpers procéduraux de
ffne se chargent pas. Les classes (ffTemplate,ffDB_Sql,Cms,Auth) arrivent par l'autoloader, mais les fonctions deff/common.php—ffCommon_dirname,ffCommon_jsonenc— non : dans le flux web c'est le bootstrap decmqui les inclut, et il ne tourne pas en CLI. Il faut les inclure explicitement. On n'inclut paslibrary/gallery/common.php, qui suppose une instance decmet un cycle de page. HTTP_HOSTdoit être préparé avantconfig.php: c'est lui qui décide de chargerconfig.local.phpouconfig.remote.php, et la moitié du framework lit$_SERVERsans vérifier les clés.FF_DISK_PATHest le chemin du SERVEUR. L'installeur y écrit/var/www/…, qui n'existe pas en local : toutrequireouload_fileconstruit sur cette constante échoue hors du serveur. Il vaut mieux définir une constante propre avec la racine réelle (depuis__DIR__) et la préférer quand elle existe ; sur le serveur les deux valeurs coïncident.
Structure conseillée d'un bootstrap CLI (bin/<projet>-bootstrap.php) :
<?php
// 1. contexte HTTP minimal, AVANT config.php
$_SERVER["HTTP_HOST"] = getenv("JC_HOST") ?: "www.esempio.it";
$_SERVER["REQUEST_URI"] = "/";
$_SERVER["SERVER_NAME"] = $_SERVER["HTTP_HOST"];
$_SERVER["REQUEST_METHOD"] = "GET";
$radice = dirname(__DIR__);
define("JC_RADICE", $radice);
require_once($radice . "/config.php");
require_once($radice . "/autoload.php");
require_once($radice . "/ff/common.php"); // les helpers procéduraux, explicitement
require_once($radice . "/ff/main.php");
// et SEULEMENT le module nécessaire : les autres accrochent des événements au cycle de page
Hôte différent : JC_HOST=sito.local php bin/<script>.php.
Script de diagnostic
Il vaut la peine d'en avoir un, avec deux modes :
php bin/<projet>-diagnostica.php # lectures seules : exécutable en production
php bin/<projet>-diagnostica.php --scrivi # inclut les tests qui écrivent
qui sorte avec le code 1 si une vérification critique échoue : ainsi il entre dans une checklist de déploiement.
7. Vérifier l'interface sans connexion
Pour le backend, qui exige une session, la méthode éprouvée est une maquette HTML qui lie les CSS réels plus le DOM du composant, avec des captures depuis Chrome headless. Pour les dialogues il faut une largeur en px inline sur .ui-dialog-content, sinon le layout n'est pas représentatif.
Pour le front-end public, les pages se vérifient en les exécutant : ce sont des contrôleurs PHP, pas des fichiers statiques.
8. Lint après chaque modification de masse
Non négociable sur cette base de code :
find . -name '*.php' -print0 | xargs -0 -n1 /opt/homebrew/opt/php@8.1/bin/php -n -l \
| grep -v 'No syntax errors'
Le dépôt porte encore les traces d'un vieux sed de masse qui avait corrompu des milliers de tokens dans des bibliothèques tierces (PHPExcel, TCPDF, SEOstats) et même les quantificateurs regex {1,3} → [1,3]. L'histoire est dans MIGRAZIONE_PHP7_PHP8.md.
Et pour les templates, la vérification des marqueurs <!--Begin…--> / <!--End…--> (voir 02 §2.2) :
grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \
--include='*.html' --include='*.php' . | grep -v '/docs/' | wc -l # doit donner 0