Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 13

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 1 dans le .htaccess (ou dans le vhost), ou la variable d'environnement JC_DEBUG_ALLOWED=1 pour le serveur de PHP ;
  • une copie de travail .local vue depuis la machine elle-même (REMOTE_ADDR de 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), et JC_DEBUG_ALLOWED ne doit pas rester allumé en production.

3. Logs

OutilOù 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 PHPlog du serveur web — le repli qui fonctionne toujours
vendor/hcore/logs/abstraction avec un service splunk
library/gallery/system/trace.phpsuivi 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_DSN dans 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

OutilQuoi
conf/profiling/{admin,data-entry,user}.xmlprofils 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.phpvé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 :

  1. Les helpers procéduraux de ff ne se chargent pas. Les classes (ffTemplate, ffDB_Sql, Cms, Auth) arrivent par l'autoloader, mais les fonctions de ff/common.php — ffCommon_dirname, ffCommon_jsonenc — non : dans le flux web c'est le bootstrap de cm qui les inclut, et il ne tourne pas en CLI. Il faut les inclure explicitement. On n'inclut pas library/gallery/common.php, qui suppose une instance de cm et un cycle de page.
  2. HTTP_HOST doit être préparé avant config.php : c'est lui qui décide de charger config.local.php ou config.remote.php, et la moitié du framework lit $_SERVER sans vérifier les clés.
  3. FF_DISK_PATH est le chemin du SERVEUR. L'installeur y écrit /var/www/…, qui n'existe pas en local : tout require ou load_file construit 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