Skip to content
JoeCMS Download 3.1.5
Manual · 13

Observability, diagnostics and CLI

How to see what's going on in a stack where errors can't be printed.

1. The basic rule: display_errors = 0, always

ff/error_handling.php centralises error handling and forces display_errors to 0. It's not a preference, it's a structural constraint: a printed warning

  • corrupts the binary output of images served by showfiles,
  • breaks the headers of a JSON response,
  • and in any case shows paths and queries to the user.

PHP 8.2's "dynamic properties" deprecations are silenced, not fixed: there are thousands of them in a 14,400-file codebase, and fixing them would be a rewrite.

1bis. What the visitor sees: the error document and maintenance

A 404 decided by the router, an Apache 404/403 (ErrorDocument → cm/error.php) and a fatal error all end up in cms_error_document() (cm/errori.php): JSON for XHR and API calls, otherwise the page cm/extras/404.html or cm/extras/500.html (a branded one in conf/cm/extras/ wins), with a reference to find in the log. The page does not go through ffTemplate, because it must show even with the framework broken: the placeholders ({titolo}, {sommario}, {url_home}, …, plus {ID_richiesta}, {URL_richiesta} and {anno}) are filled by cms_error_testi() with strtr().

The texts are in four languages inside cm/errori.php, because the database may not be there. cms_error_lingua() chooses: the language decided by the kernel (LANGUAGE_INSET_TINY), if any; the address prefix (/en/…); the browser (Accept-Language); Italian. An active language without texts gets English. Home and sign-in point to the same language (/fr, /fr/login).

The maintenance page (cm/maintenance.php, when the .maintenance file exists) runs before config and kernel, so it picks the language only from the address and the browser, with the same function. It ends with exit: up to 3.0.3 it did not, and after the 503 page index.php started the CMS anyway, which is exactly what maintenance must prevent during an update.

2. On-demand debugging: ?__debug__

https://site/page?__debug__

ff/error_handling.php:51 re-enables display_errors for that single request. It's the intended way to look at an error in an environment where display_errors must stay off.

Who can use it. cm/livello-errori.php, the first file included by every entry point (the API included), removes __debug__ and __query__ from the request for anyone who may not ask for them, so the rest of the CMS doesn't see them. They can be asked for by:

  • the command line;
  • the server that grants it on purpose: SetEnv JC_DEBUG_ALLOWED 1 in the .htaccess (or in the vhost), or the JC_DEBUG_ALLOWED=1 environment variable for PHP's built-in server;
  • a .local working copy seen from the machine itself (loopback REMOTE_ADDR).

On staging and production, then, nothing switches on by default: to look at an error there you set the SetEnv for as long as needed and then remove it.

In the code, two predicates govern the behaviour:

ffErrorHandler::logEnabled();    // writes to the log
ffErrorHandler::hideEnabled();   // hides on screen — false when __debug__ is present

And ffErrorHandler::raise($message, E_USER_ERROR, $context, $variables) is available to raise an application error that goes through the same chain (with stack trace, compacted constants and structured output).

⚠️ ?__debug__ is useful and should be treated as a diagnostics feature in production: it exposes paths, queries and variables. Up to 1.6.2 anyone could ask for it; since 1.7.0 it is closed by default (see above), and JC_DEBUG_ALLOWED must not be left on in production.

3. Logs

ToolWhere it writes
Cache::log($data, $filename)log file in the cache folder (cache/logs/); it's what the service bus uses for request_error_js / request_error_css. cache/logs/ is closed to the browser by the .htaccess: up to 3.1.0 the day's logs could be downloaded (14 §3)
PHP's error_log()web server log — the fallback that always works
vendor/hcore/logs/abstraction with a splunk service
library/gallery/system/trace.phpvisit tracking (system_trace, system_write_trace), with crawler detection (system_trace_isCrawler) and visitor profile
vendor/hcore/stats/statistics: action, page, trace, user, visitor

For a new subsystem, the proven pattern is a dedicated log file, on by default and switchable off from configuration, with one line per event and a recognisable outcome. It's needed above all for webhooks and jobs: without it, triage is impossible (03 §2).

4. Sentry

Initialised in hook.php right after the domain is defined:

require_once(__DIR__ . "/library/sentry/bootstrap.php");
cms_sentry_init();
  • driven by SENTRY_DSN in the configuration (the wizard asks for it, Services step);
  • defensive: a no-op if the DSN is missing or the library isn't there;
  • the domain is only used as the environment label (production / staging).

5. Profiling and diagnostics

ToolWhat
conf/profiling/{admin,data-entry,user}.xmlprofiling profiles per role
MOD_SEC_PROFILING (hook.php)switch, false by default; a site changes it in the config
conf/gallery/job/diagnostic/checks cache, dictionary, config, uploads, thumbs and writes the result as a backend notification
library/gallery/common/check_system.php, check_fs.phpsystem and filesystem checks
library/gallery/job.php → get_check_fs()permissions and sizes of the file tree

6. Command-line execution

It's for workers, maintenance scripts, diagnostics and automated tests. From the CLI the stack behaves differently in three ways, all capable of producing a fatal error you don't see from the web:

  1. ff's procedural helpers aren't loaded. Classes (ffTemplate, ffDB_Sql, Cms, Auth) come from the autoloader, but the functions in ff/common.php — ffCommon_dirname, ffCommon_jsonenc — don't: in the web flow cm's bootstrap includes them, and it doesn't run from the CLI. They must be included explicitly. Don't include library/gallery/common.php, which assumes a cm instance and a page cycle.
  2. HTTP_HOST must be set before config.php: it decides whether to load config.local.php or config.remote.php, and half the framework reads $_SERVER without checking keys.
  3. FF_DISK_PATH is the SERVER path. The installer writes /var/www/… into it, which doesn't exist locally: any require or load_file built on that constant fails off the server. It's worth defining an own constant with the real root (from __DIR__) and preferring it when present; on the server the two values coincide.

Recommended structure of a CLI bootstrap (bin/<project>-bootstrap.php):

<?php
// 1. minimal HTTP context, BEFORE 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");     // the procedural helpers, explicitly
require_once($radice . "/ff/main.php");
// and ONLY the module you need: the others hook events into the page cycle

Different host: JC_HOST=sito.local php bin/<script>.php.

Diagnostics script

It's worth having one, with two modes:

php bin/<project>-diagnostica.php            # read-only: can run in production
php bin/<project>-diagnostica.php --scrivi   # includes the tests that write

that exits with code 1 if a critical check fails: that way it fits into a deploy checklist.

7. Checking the interface without logging in

For the backend, which requires a session, the proven method is an HTML mock linking the live CSS plus the component's DOM, with screenshots from headless Chrome. For dialogs you need an inline px width on .ui-dialog-content, otherwise the layout isn't representative.

For the public front end, pages are checked by running them: they're PHP controllers, not static files.

8. Lint after every mass change

Non-negotiable on this codebase:

find . -name '*.php' -print0 | xargs -0 -n1 /opt/homebrew/opt/php@8.1/bin/php -n -l \
  | grep -v 'No syntax errors'

The repo still bears the marks of an old mass sed that had corrupted thousands of tokens in third-party libraries (PHPExcel, TCPDF, SEOstats) and even regex quantifiers {1,3} → [1,3]. The story is in MIGRAZIONE_PHP7_PHP8.md.

And for templates, the check on the <!--Begin…--> / <!--End…--> markers (see 02 §2.2):

grep -rIE '<!--[[:space:]]+(Begin|End)[A-Za-z0-9_]+[[:space:]]*-->' \
     --include='*.html' --include='*.php' . | grep -v '/docs/' | wc -l    # must give 0