Observabilidad, diagnóstico y CLI
Cómo se ve lo que está pasando en un stack donde los errores no se pueden imprimir.
1. La regla de base: display_errors = 0, siempre
ff/error_handling.php centraliza la gestión de errores y fuerza display_errors a 0. No es una preferencia, es una restricción estructural: un warning impreso
- corrompe la salida binaria de las imágenes servidas por
showfiles, - rompe las cabeceras de una respuesta JSON,
- y en cualquier caso muestra rutas y queries al usuario.
Las deprecaciones de "propiedades dinámicas" de PHP 8.2 están silenciadas, no corregidas: son miles en una base de código de 14.400 archivos, y corregirlas sería una reescritura.
1bis. Qué ve el visitante: el documento de error y el mantenimiento
Un 404 decidido por el router, un 404/403 de Apache (ErrorDocument → cm/error.php) y un error fatal acaban en cms_error_document() (cm/errori.php): JSON para las llamadas XHR y API, y si no la página cm/extras/404.html o cm/extras/500.html (una de marca en conf/cm/extras/ tiene prioridad), con una referencia para encontrar en el log. La página no pasa por ffTemplate, porque debe mostrarse incluso con el framework roto: los marcadores ({titolo}, {sommario}, {url_home}, …, además de {ID_richiesta}, {URL_richiesta} y {anno}) los rellena cms_error_testi() con strtr().
Los textos están en cuatro idiomas dentro de cm/errori.php, porque aquí puede no haber base de datos. cms_error_lingua() elige: el idioma decidido por el kernel (LANGUAGE_INSET_TINY), si lo hay; el prefijo de la dirección (/en/…); el navegador (Accept-Language); el italiano. Un idioma activo pero sin textos recibe el inglés. Inicio y acceso apuntan al mismo idioma (/fr, /fr/login).
La página de mantenimiento (cm/maintenance.php, cuando existe el archivo .maintenance) se ejecuta antes que el config y el kernel, así que elige el idioma solo por la dirección y el navegador, con la misma función. Termina con exit: hasta la 3.0.3 no lo hacía, y tras la página 503 index.php arrancaba igualmente el CMS, justo lo que el mantenimiento debe evitar durante una actualización.
2. Debug bajo demanda: ?__debug__
https://sitio/pagina?__debug__
ff/error_handling.php:51 reactiva display_errors para esa sola petición. Es la forma prevista de mirar un error en un entorno donde display_errors debe seguir apagado.
Quién puede usarlo. cm/livello-errori.php, el primer archivo que incluye cada punto de entrada (API incluida), quita __debug__ y __query__ de la petición a quien no puede pedirlos, así el resto del CMS no los ve. Pueden pedirlos:
- la línea de comandos;
- el servidor que lo concede a propósito:
SetEnv JC_DEBUG_ALLOWED 1en el.htaccess(o en el vhost), o la variable de entornoJC_DEBUG_ALLOWED=1para el servidor de PHP; - una copia de trabajo
.localvista desde la propia máquina (REMOTE_ADDRde loopback).
En staging y producción, por tanto, por defecto no se enciende nada: para mirar un error allí se pone el SetEnv el tiempo necesario y luego se quita.
En el código, dos predicados gobiernan el comportamiento:
ffErrorHandler::logEnabled(); // escribe en el log
ffErrorHandler::hideEnabled(); // oculta en pantalla — false cuando está __debug__
Y está disponible ffErrorHandler::raise($mensaje, E_USER_ERROR, $context, $variables) para lanzar un error de aplicación que pasa por la misma cadena (con stack trace, constantes compactadas e impresión estructurada).
⚠️
?__debug__es útil y debe tratarse como una función de diagnóstico en producción: expone rutas, queries y variables. Hasta la 1.6.2 podía pedirlo cualquiera; desde la 1.7.0 está cerrado por defecto (ver arriba), yJC_DEBUG_ALLOWEDno debe quedarse encendido en producción.
3. Logs
| Herramienta | Dónde escribe |
|---|---|
Cache::log($data, $filename) | archivo de log en la carpeta de caché (cache/logs/); es el que usa el bus de servicios para request_error_js / request_error_css. cache/logs/ está cerrada al navegador por el .htaccess: hasta la 3.1.0 los logs del día se podían descargar (14 §3) |
error_log() de PHP | log del servidor web — el fallback que siempre funciona |
vendor/hcore/logs/ | abstracción con servicio splunk |
library/gallery/system/trace.php | seguimiento de visitas (system_trace, system_write_trace), con reconocimiento de crawlers (system_trace_isCrawler) y perfil del visitante |
vendor/hcore/stats/ | estadísticas: action, page, trace, user, visitor |
Para un subsistema nuevo, el patrón probado es un archivo de log dedicado, encendido por defecto y apagable desde la configuración, con una línea por evento y un resultado reconocible. Sirve sobre todo para webhooks y jobs: sin él, el triaje es imposible (03 §2).
4. Sentry
Inicializado en hook.php justo después de la definición del dominio:
require_once(__DIR__ . "/library/sentry/bootstrap.php");
cms_sentry_init();
- guiado por
SENTRY_DSNen la configuración (lo pide el asistente, paso Servicios); - defensivo: no hace nada si falta el DSN o si la librería no está;
- el dominio sirve solo como etiqueta de entorno (
production/staging).
5. Profiling y diagnóstico
| Herramienta | Qué |
|---|---|
conf/profiling/{admin,data-entry,user}.xml | perfiles de profiling por rol |
MOD_SEC_PROFILING (hook.php) | interruptor, false por defecto; un sitio lo cambia en el config |
conf/gallery/job/diagnostic/ | verifica caché, diccionario, config, uploads, miniaturas y escribe el resultado como notificación de backend |
library/gallery/common/check_system.php, check_fs.php | verificaciones de sistema y filesystem |
library/gallery/job.php → get_check_fs() | permisos y tamaños del árbol de archivos |
6. Ejecución desde línea de comandos
Sirve para workers, scripts de mantenimiento, diagnóstico y pruebas automáticas. Desde CLI el stack se comporta de forma distinta en tres aspectos, todos capaces de producir un fatal que no se ve desde la web:
- Los helpers procedurales de
ffno se cargan. Las clases (ffTemplate,ffDB_Sql,Cms,Auth) llegan del autoloader, pero las funciones deff/common.php—ffCommon_dirname,ffCommon_jsonenc— no: en el flujo web las incluye el bootstrap decm, que desde CLI no se ejecuta. Hay que incluirlas explícitamente. No se incluyelibrary/gallery/common.php, que presupone una instancia decmy un ciclo de página. HTTP_HOSTdebe prepararse antes deconfig.php: es él quien decide si cargarconfig.local.phpoconfig.remote.php, y medio framework lee$_SERVERsin verificar las claves.FF_DISK_PATHes la ruta del SERVIDOR. El instalador escribe ahí/var/www/…, que en local no existe: cualquierrequireoload_fileconstruido sobre esa constante falla fuera del servidor. Conviene definir una constante propia con la raíz real (desde__DIR__) y preferirla cuando existe; en el servidor los dos valores coinciden.
Estructura recomendada de un bootstrap CLI (bin/<proyecto>-bootstrap.php):
<?php
// 1. contexto HTTP mínimo, ANTES de 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"); // los helpers procedurales, explícitamente
require_once($radice . "/ff/main.php");
// y SOLO el módulo que hace falta: los demás enganchan eventos al ciclo de página
Host distinto: JC_HOST=sito.local php bin/<script>.php.
Script de diagnóstico
Merece la pena tener uno, con dos modalidades:
php bin/<proyecto>-diagnostica.php # solo lecturas: ejecutable en producción
php bin/<proyecto>-diagnostica.php --scrivi # incluye las pruebas que escriben
que salga con código 1 si una verificación crítica falla: así entra en una checklist de despliegue.
7. Verificar la interfaz sin login
Para el backend, que requiere una sesión, el método probado es un mock HTML que enlaza los CSS reales más el DOM del componente, con capturas desde Chrome headless. Para los diálogos hace falta un ancho en px inline en .ui-dialog-content, si no el layout no es representativo.
Para el front-end público, las páginas se verifican ejecutándolas: son controladores PHP, no archivos estáticos.
8. Lint después de cada modificación masiva
No negociable en esta base de código:
find . -name '*.php' -print0 | xargs -0 -n1 /opt/homebrew/opt/php@8.1/bin/php -n -l \
| grep -v 'No syntax errors'
El repo aún lleva las marcas de un viejo sed masivo que había corrompido miles de tokens en librerías de terceros (PHPExcel, TCPDF, SEOstats) e incluso los cuantificadores regex {1,3} → [1,3]. La historia está en MIGRAZIONE_PHP7_PHP8.md.
Y para las plantillas, la verificación de los marcadores <!--Begin…--> / <!--End…--> (ver 02 §2.2):
grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \
--include='*.html' --include='*.php' . | grep -v '/docs/' | wc -l # debe dar 0