Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 13

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 1 en el .htaccess (o en el vhost), o la variable de entorno JC_DEBUG_ALLOWED=1 para el servidor de PHP;
  • una copia de trabajo .local vista desde la propia máquina (REMOTE_ADDR de 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), y JC_DEBUG_ALLOWED no debe quedarse encendido en producción.

3. Logs

HerramientaDó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 PHPlog del servidor web — el fallback que siempre funciona
vendor/hcore/logs/abstracción con servicio splunk
library/gallery/system/trace.phpseguimiento 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_DSN en 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

HerramientaQué
conf/profiling/{admin,data-entry,user}.xmlperfiles 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.phpverificaciones 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:

  1. Los helpers procedurales de ff no se cargan. Las clases (ffTemplate, ffDB_Sql, Cms, Auth) llegan del autoloader, pero las funciones de ff/common.php — ffCommon_dirname, ffCommon_jsonenc — no: en el flujo web las incluye el bootstrap de cm, que desde CLI no se ejecuta. Hay que incluirlas explícitamente. No se incluye library/gallery/common.php, que presupone una instancia de cm y un ciclo de página.
  2. HTTP_HOST debe prepararse antes de config.php: es él quien decide si cargar config.local.php o config.remote.php, y medio framework lee $_SERVER sin verificar las claves.
  3. FF_DISK_PATH es la ruta del SERVIDOR. El instalador escribe ahí /var/www/…, que en local no existe: cualquier require o load_file construido 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