Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 13

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 1 nel .htaccess (o nel vhost), o la variabile d'ambiente JC_DEBUG_ALLOWED=1 per il server di PHP;
  • una copia di lavoro .local vista dalla macchina stessa (REMOTE_ADDR di 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), e JC_DEBUG_ALLOWED in produzione non va lasciato acceso.

3. Log

StrumentoDove 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 PHPlog del web server — il fallback che funziona sempre
vendor/hcore/logs/astrazione con servizio splunk
library/gallery/system/trace.phptracciamento 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_DSN nella 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

StrumentoCosa
conf/profiling/{admin,data-entry,user}.xmlprofili 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.phpverifiche 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:

  1. Gli helper procedurali di ff non si caricano. Le classi (ffTemplate, ffDB_Sql, Cms, Auth) arrivano dall'autoloader, ma le funzioni di ff/common.php — ffCommon_dirname, ffCommon_jsonenc — no: nel flusso web le include il bootstrap di cm, che da CLI non gira. Vanno incluse esplicitamente. Non si include library/gallery/common.php, che presuppone un'istanza di cm e un ciclo di pagina.
  2. HTTP_HOST va predisposto prima di config.php: è lui a decidere se caricare config.local.php o config.remote.php, e mezzo framework legge $_SERVER senza verificare le chiavi.
  3. FF_DISK_PATH è il percorso del SERVER. L'installer ci scrive /var/www/…, che in locale non esiste: qualunque require o load_file costruito 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