Download the PHP package pringuin/opendxp-health-bundle without Composer

Pringuin OpenDXP Health Bundle

Health checks for OpenDXP projects. Runs a set of checks via CLI command (cron) or from the admin UI, stores the latest report for display in the admin and optionally sends it via email.

Checks

Additional checks can be added by implementing Pringuin\OpenDxpHealthBundle\Check\HealthCheckInterface — implementations are picked up automatically (autoconfigured service tag pringuin_opendxp_health.check).

Installation

Register the bundle in config/bundles.php:

Install the bundle (registers the pringuin_health admin permission):

Grant the pringuin_health permission (category "Pringuin Health Bundle") to the users/roles that should see the report in the admin UI.

Configuration

All keys with their defaults (config/packages/pringuin_opendxp_health.yaml):

The email_log send volume check is off by default because the normal volume differs per project. Set max_emails_per_window to a value clearly above the regular peak (including newsletter or campaign sends) — its purpose is to catch mail loops and runaway jobs, not to police everyday traffic:

The check does not just count the emails since the last run: it looks for the busiest window_minutes long window anywhere within max_age_hours, so a burst is still reported when the check runs only once a day. window_minutes must therefore not exceed max_age_hours.

The ssl_certificate check connects from the server to the domains itself; if internal DNS or firewall rules prevent that, configure reachable domains explicitly or disable the check. Without configured domains it connects to every domain entered in the system settings and the sites. Admin users who may edit sites can thereby make the server open TLS connections to arbitrary hosts on the configured port, and the connection errors in the report reveal whether such a host is reachable from the server. On servers with access to sensitive internal networks, configure domains explicitly so the site settings are not used.

The environment check reports critical on every non-prod system by design. Disable it for local development in config/packages/dev/pringuin_opendxp_health.yaml:

Note on failed_messages: OpenDXP does not configure a messenger failure_transport by default — messages that exhaust their retries are then discarded silently. Recommended project configuration:

Note on composer_audit / composer_outdated: composer runs as the PHP process user. The binary is taken from COMPOSER_BINARY (environment or .env.local), then composer in PATH, composer.phar in the project root and common install paths. Use Composer >= 2.8 — older versions emit PHP 8.4 deprecation notices and have known vulnerabilities. Private repositories need credentials, just like composer install: a project auth.json, COMPOSER_AUTH or the global auth.json in the user's composer home (COMPOSER_HOME, ~/.config/composer or ~/.composer). Without HOME (e.g. php-fpm with clear_env), the home directory of the process user's passwd entry is used; if that is unavailable too, var/pringuin-health-composer-home in the project. Composer runs with --no-plugins, so no plugin code is executed from within a web request; repositories that are only reachable through a composer plugin are therefore not supported. A failed composer run is retried once after a few seconds. If composer still cannot reach packagist.org or another repository (e.g. curl error, Could not resolve host), both checks report a warning instead of an error, so short network outages do not trigger error mails.

Usage

CLI / Cron

--mail, --no-mail and --mail-min-status all decide the same thing and therefore cannot be combined. --mail-min-status also sends when mail.enabled is false, because passing it is an explicit request for that run.

Exit codes: 0 = healthy, 1 = issues found, 2 = a check could not be executed, mail delivery failed or another run was still in progress (useful in combination with cron MAILTO).

Only one run can happen at a time: the command and the "Run now" button in the admin UI share a lock (Symfony Lock, stored in the database by OpenDXP). A second run is refused instead of starting the composer processes again; the admin UI answers with HTTP 409.

Cron example (every night at 03:17):

Mail threshold

A mail is sent when the overall status of the report is at least as severe as the threshold. The severity order is ok < warning < critical < error (error means a check itself could not be executed, e.g. a missing composer binary), so min_status: critical also mails execution errors.

Two schedules, one for urgent findings and one for the full picture:

Every run stores its report for the admin UI regardless of the threshold, and every mail contains the complete report, not just the findings above the threshold.

Admin UI

Menu Tools → Health Report (requires the pringuin_health permission): shows the last stored report and offers Run checks now and Send report via email.

The window lists every check with its status badge, a summary line and the findings behind it. Scrolled through on a deliberately unhealthy demo installation:

Dashboard portlet: on a dashboard (e.g. the Welcome tab), use Add portlet → Health Report to pin a compact status overview (overall status, per-check badges, issue summaries). The portlet's header tools refresh it and open the full report window. It is only offered to users with the pringuin_health permission.

The admin UI labels follow the admin user's language; German and English ship with the bundle (translations/admin.de.yaml, translations/admin.en.yaml), which is why the screenshots above are German. The check summaries and details in the report itself are English.

Note: running the checks from the admin executes composer audit and composer outdated synchronously; depending on network speed this can take a while and may hit the PHP/web server request timeouts. Prefer the cron run for regular reports.

Status endpoint (external monitoring)

A public, token-protected endpoint exposes the status of the last stored report for uptime monitors (Uptime Kuma, Icinga, UptimeRobot, ...). It is disabled by default; enable it and set a random token of at least 32 characters (e.g. openssl rand -hex 32):

Send the token as a header where the monitor supports it. ?token=<token> is accepted as well for monitors that cannot set headers, but query strings end up in access and proxy logs.

• HTTP 200 when the last report is healthy, 503 when it contains issues or no report exists yet — so a monitor can alert on the status code alone.
• The JSON body contains the overall status, the issue count, the report date and the status of each check. The check summaries and details are only included with expose_details: true: they can contain admin user names, email addresses, log excerpts and vulnerable package versions.
• 403 on a missing/wrong token (logged as a warning); 404 when disabled or no token of at least 32 characters is configured (the endpoint never reveals itself unauthenticated; a too short token is logged as an error).
• Every response is sent with Cache-Control: no-store, so neither the OpenDXP full page cache nor a reverse proxy serves a stale "healthy" answer.

The endpoint only returns the stored report; it never runs the checks itself, so it cannot be used to trigger expensive work. Run pringuin:health:check via cron to keep it fresh, and put the endpoint behind a rate limit at the web-server/proxy layer.

Development

The suite consists of unit tests only — no database, no booted kernel. Checks that talk to the database receive a mocked Doctrine\DBAL\Connection, so the SQL itself is not executed; EmailLogCheckTest therefore asserts the window frame of the send volume query as a string. The query was verified manually against MySQL 8.0 and MariaDB 11.4.

Bundle state (the last report, the previous table size measurement) goes through Storage\SettingsStorageInterface instead of OpenDxp\Model\Tool\SettingsStore directly, so TableGrowthCheck and HealthReportStorage can run against the in-memory double in tests/Double. Add new state to that interface rather than calling the settings store from a check.

Collaborators the checks cannot reach into are injected through interfaces, so every check except the two below is covered: Storage\SettingsStorageInterface for bundle state and Util\ComposerRunnerInterface for the composer processes. The composer checks receive it wrapped in Util\ComposerJsonRunner, which owns running the command and decoding its JSON output; the doubles for both live in tests/Double/ComposerRunnerDoubles. SslCertificateCheck keeps only the TLS socket itself; the evaluation of a parsed certificate (expiry thresholds, subjectAltName and wildcard matching) lives in Util\CertificateEvaluator and is tested against plain arrays.

Not covered: CacheCheck calls the static OpenDxp\Cache facade and AdminTwoFactorCheck builds a User\Listing itself, so neither can be substituted in a unit test.

• CacheCheck would become testable by injecting OpenDxp\Cache\Core\CoreCacheHandler — the facade is only a static wrapper around that service and offers the same isEnabled(), save(), load() and remove(). All five branches of the check would then be reachable.
• AdminTwoFactorCheck cannot be covered meaningfully without a database: its logic is the listing condition. That needs a booted kernel plus an installed OpenDXP schema, i.e. a separate integration suite that cannot run standalone.

Email recipient resolution

1. pringuin_opendxp_health.mail.recipient if configured
2. Otherwise the main email address from the OpenDXP system settings (opendxp.email.sender.email)

The sender address is taken automatically from the OpenDXP email system settings (OpenDxp\Mail default behavior).

Security

Please do not report vulnerabilities in public issues — see SECURITY.md.

License

Copyright (C) PRinguin GbR (Daniel Brinkmann & Lennart Fries)

This bundle is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version — the same license as OpenDXP itself. See LICENSE for the full text.