Osservabilità, diagnostica e CLI
Come si vede cosa sta succedendo su uno stack dove gli errori non si possono stampare.
1. La regola di base: display_errors = 0, sempre
ff/error_handling.php centralizza la gestione degli errori e forza display_errors a 0. Non è una preferenza, è un vincolo strutturale: un warning stampato
- corrompe l'output binario delle immagini servite da
showfiles, - rompe gli header di una risposta JSON,
- e comunque mostra percorsi e query all'utente.
Le deprecation "proprietà dinamiche" di PHP 8.2 sono silenziate, non corrette: sono migliaia su una codebase di 14.400 file, e correggerle sarebbe una riscrittura.
1bis. Cosa vede il visitatore: documento d'errore e manutenzione
Un 404 deciso dal router, un 404/403 di Apache (ErrorDocument → cm/error.php) e un errore fatale finiscono in cms_error_document() (cm/errori.php): JSON per le chiamate XHR e API, altrimenti la pagina cm/extras/404.html o cm/extras/500.html (una di marca in conf/cm/extras/ vince), con un riferimento da ritrovare nel log. La pagina non passa da ffTemplate, perché deve mostrarsi anche con il framework rotto: i segnaposto ({titolo}, {sommario}, {url_home}, …, oltre a {ID_richiesta}, {URL_richiesta} e {anno}) li riempie cms_error_testi() con strtr().
I testi sono in quattro lingue dentro cm/errori.php, perché qui il database può non esserci. cms_error_lingua() sceglie: la lingua decisa dal kernel (LANGUAGE_INSET_TINY), se c'è; il prefisso dell'indirizzo (/en/…); il browser (Accept-Language); l'italiano. Una lingua attiva ma senza testi riceve l'inglese. Home e accesso puntano alla stessa lingua (/fr, /fr/login).
La pagina di manutenzione (cm/maintenance.php, quando c'è il file .maintenance) gira prima di config e kernel, quindi sceglie la lingua solo da indirizzo e browser, con la stessa funzione. Finisce con exit: fino alla 3.0.3 non lo faceva, e dopo la pagina 503 index.php avviava comunque il CMS, cioè proprio quello che la manutenzione deve evitare durante un aggiornamento.
2. Debug on-demand: ?__debug__
https://sito/pagina?__debug__
ff/error_handling.php:51 riattiva display_errors per quella sola richiesta. È il modo previsto per guardare un errore in un ambiente dove display_errors deve restare spento.
Chi può usarlo. cm/livello-errori.php, il primo file incluso da ogni ingresso (API compresa), toglie __debug__ e __query__ dalla richiesta a chi non li può chiedere, così il resto del CMS non li vede. Possono chiederli:
- la riga di comando;
- il server che lo concede apposta:
SetEnv JC_DEBUG_ALLOWED 1nel.htaccess(o nel vhost), o la variabile d'ambienteJC_DEBUG_ALLOWED=1per il server di PHP; - una copia di lavoro
.localvista dalla macchina stessa (REMOTE_ADDRdi loopback).
Su staging e produzione, quindi, per difetto non si accende niente: per guardare un errore lì si mette la SetEnv per il tempo che serve e poi la si toglie.
Nel codice, due predicati governano il comportamento:
ffErrorHandler::logEnabled(); // scrive nel log
ffErrorHandler::hideEnabled(); // nasconde a video — false quando c'è __debug__
Ed è disponibile ffErrorHandler::raise($messaggio, E_USER_ERROR, $context, $variables) per sollevare un errore applicativo che passa dalla stessa catena (con stack trace, costanti compattate e stampa strutturata).
⚠️
?__debug__è utile e va trattato come una funzione di diagnostica in produzione: espone percorsi, query e variabili. Fino alla 1.6.2 lo poteva chiedere chiunque; dalla 1.7.0 è chiuso per difetto (vedi sopra), eJC_DEBUG_ALLOWEDin produzione non va lasciato acceso.
3. Log
| Strumento | Dove scrive |
|---|---|
Cache::log($data, $filename) | file di log nella cartella di cache (cache/logs/); è quello usato dal bus dei servizi per request_error_js / request_error_css. cache/logs/ è chiusa al browser dal .htaccess: fino alla 3.1.0 i log del giorno si scaricavano (14 §3) |
error_log() di PHP | log del web server — il fallback che funziona sempre |
vendor/hcore/logs/ | astrazione con servizio splunk |
library/gallery/system/trace.php | tracciamento delle visite (system_trace, system_write_trace), con riconoscimento crawler (system_trace_isCrawler) e profilo visitatore |
vendor/hcore/stats/ | statistiche: action, page, trace, user, visitor |
Per un sottosistema nuovo, il pattern collaudato è un file di log dedicato, acceso di default e spegnibile da configurazione, con una riga per evento e un esito riconoscibile. Serve soprattutto per i webhook e i job: senza, il triage è impossibile (03 §2).
4. Sentry
Inizializzato in hook.php subito dopo la definizione del dominio:
require_once(__DIR__ . "/library/sentry/bootstrap.php");
cms_sentry_init();
- guidato da
SENTRY_DSNnella configurazione (lo chiede il wizard, step Servizi); - difensivo: no-op se il DSN manca o se la libreria non c'è;
- il dominio serve solo come etichetta di environment (
production/staging).
5. Profiling e diagnostica
| Strumento | Cosa |
|---|---|
conf/profiling/{admin,data-entry,user}.xml | profili di profiling per ruolo |
MOD_SEC_PROFILING (hook.php) | interruttore, false di default; un sito lo cambia nel config |
conf/gallery/job/diagnostic/ | verifica cache, dizionario, config, uploads, thumb e scrive il risultato come notifica di backend |
library/gallery/common/check_system.php, check_fs.php | verifiche di sistema e filesystem |
library/gallery/job.php → get_check_fs() | permessi e dimensioni dell'albero dei file |
6. Esecuzione da riga di comando
Serve per worker, script di manutenzione, diagnostica e prove automatiche. Da CLI lo stack si comporta diversamente in tre modi, tutti capaci di produrre un fatal che non si vede dal web:
- Gli helper procedurali di
ffnon si caricano. Le classi (ffTemplate,ffDB_Sql,Cms,Auth) arrivano dall'autoloader, ma le funzioni diff/common.php—ffCommon_dirname,ffCommon_jsonenc— no: nel flusso web le include il bootstrap dicm, che da CLI non gira. Vanno incluse esplicitamente. Non si includelibrary/gallery/common.php, che presuppone un'istanza dicme un ciclo di pagina. HTTP_HOSTva predisposto prima diconfig.php: è lui a decidere se caricareconfig.local.phpoconfig.remote.php, e mezzo framework legge$_SERVERsenza verificare le chiavi.FF_DISK_PATHè il percorso del SERVER. L'installer ci scrive/var/www/…, che in locale non esiste: qualunquerequireoload_filecostruito su quella costante fallisce fuori dal server. Conviene definire una costante propria con la radice reale (da__DIR__) e preferirla quando c'è; sul server i due valori coincidono.
Struttura consigliata di un bootstrap CLI (bin/<progetto>-bootstrap.php):
<?php
// 1. contesto HTTP minimo, PRIMA di 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"); // gli helper procedurali, esplicitamente
require_once($radice . "/ff/main.php");
// e SOLO il modulo che serve: gli altri agganciano eventi al ciclo di pagina
Host diverso: JC_HOST=sito.local php bin/<script>.php.
Script di diagnostica
Vale la pena averne uno, con due modalità:
php bin/<progetto>-diagnostica.php # solo letture: eseguibile in produzione
php bin/<progetto>-diagnostica.php --scrivi # include le prove che scrivono
che esca con codice 1 se una verifica critica fallisce: così entra in una checklist di deploy.
7. Verificare l'interfaccia senza login
Per il backend, che richiede una sessione, il metodo collaudato è un mock HTML che linka i CSS live più il DOM del componente, con screenshot da Chrome headless. Per i dialog serve una width in px inline su .ui-dialog-content, altrimenti il layout non è rappresentativo.
Per il frontend pubblico, le pagine si verificano eseguendole: sono controller PHP, non file statici.
8. Lint dopo ogni modifica di massa
Non negoziabile su questa codebase:
find . -name '*.php' -print0 | xargs -0 -n1 /opt/homebrew/opt/php@8.1/bin/php -n -l \
| grep -v 'No syntax errors'
Il repo porta ancora i segni di un vecchio sed di massa che aveva corrotto migliaia di token in librerie terze (PHPExcel, TCPDF, SEOstats) e persino i quantificatori regex {1,3} → [1,3]. La storia è in MIGRAZIONE_PHP7_PHP8.md.
E per i template, la verifica dei marker <!--Begin…--> / <!--End…--> (vedi 02 §2.2):
grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \
--include='*.html' --include='*.php' . | grep -v '/docs/' | wc -l # deve dare 0