PHPackages                             worlddirect/healthcheck - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. worlddirect/healthcheck

ActiveTypo3-cms-extension[Logging & Monitoring](/categories/logging)

worlddirect/healthcheck
=======================

Check the health of your TYPO3 installation.

4.5.3(2mo ago)58.7k↓43.6%2[5 issues](https://github.com/world-direct-cms/wd-ext-healthcheck/issues)GPL-2.0-onlyPHPPHP ^8.1 || ^8.2 || ^8.3 || ^8.4

Since Apr 12Pushed 2mo agoCompare

[ Source](https://github.com/world-direct-cms/wd-ext-healthcheck)[ Packagist](https://packagist.org/packages/worlddirect/healthcheck)[ RSS](/packages/worlddirect-healthcheck/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (54)Used By (0)

TYPO3 Extension: Healthcheck
============================

[](#typo3-extension-healthcheck)

[![TYPO3](https://camo.githubusercontent.com/79dbc379464ff3ee60b5f945560761a1cf8a037e58be415cf369589cfa686e0e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d3131253230253743253230313225323025374325323031332d6f72616e67652e737667)](https://typo3.org/)[![License](https://camo.githubusercontent.com/fc7ef0bd4e7daa962ca0072e865f9970ee5441edb26f5fca76d6e7f0d3805a70/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d322e302d626c75652e737667)](LICENSE)

A comprehensive health monitoring extension for TYPO3 CMS that provides automated system checks and monitoring capabilities.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Extension Configuration](#extension-configuration)
    - [TypoScript Configuration](#typoscript-configuration)
- [Probes](#probes)
    - [Core Probes](#core-probes)
    - [Extension-Specific Probes](#extension-specific-probes)
    - [Creating Custom Probes](#creating-custom-probes)
- [Output Formats](#output-formats)
    - [HTML Output](#html-output)
    - [JSON Output](#json-output)
    - [Creating Custom Outputs](#creating-custom-outputs)
- [Accessing the Healthcheck](#accessing-the-healthcheck)
- [Pausing Probes](#pausing-probes)
- [HTTP Status Codes](#http-status-codes)
- [Troubleshooting](#troubleshooting)
- [Support](#support)
- [License](#license)
- [Credits](#credits)

Features
--------

[](#features)

- **Proactive Monitoring**: Automatically detects issues before they impact your users
- **System Overview**: Provides a quick snapshot of your TYPO3 system's health status
- **Integration Ready**: Works seamlessly with monitoring tools like PRTG, Nagios, Zabbix, and other monitoring solutions
- **Extensible Architecture**: Easily extend with custom probes specific to your needs
- **Visual Feedback**: Beautiful HTML interface showing all check results at a glance
- **API Access**: JSON output for programmatic access and automated monitoring
- **Flexible Probes**: Built-in checks for databases, caches, scheduler, Solr, email delivery, and more
- **Pause Controls**: Temporarily disable probes during maintenance without affecting monitoring
- **Security First**: IP and host-based access restrictions

Requirements
------------

[](#requirements)

- TYPO3 11.0 - 13.9
- PHP 8.1 or higher

Installation
------------

[](#installation)

### Via Composer (recommended)

[](#via-composer-recommended)

```
composer require worlddirect/healthcheck
```

### Activation

[](#activation)

After installation, activate the extension in the TYPO3 Extension Manager or via CLI:

```
php vendor/bin/typo3 extension:activate healthcheck
```

Configuration
-------------

[](#configuration)

### Extension Configuration

[](#extension-configuration)

Configure the extension through the TYPO3 Extension Manager or by editing your site's configuration.

#### Security Settings

[](#security-settings)

SettingDescriptionDefaultRequired**pathSegment**The URL path segment used to access the healthcheck (e.g., "healthcheck")`healthcheck`Yes**trustedHostsPattern**Regular expression pattern defining which hosts can access the healthcheck. Use `.*` to allow all hosts or `^(localhost|monitoring\.example\.com)$`*(empty)***Yes****allowedIps**Comma-separated list of IP addresses allowed to access. Use `*` to allow all IPs`*`No#### Display Settings

[](#display-settings)

SettingDescriptionDefault**logoImage**Path to the logo image displayed in HTML output`EXT:healthcheck/Resources/Public/Icons/healthreport.png`**backgroundImage**Path to the background image for HTML output`EXT:healthcheck/Resources/Public/Images/background.png`**enableBuildinfo**Show build information (requires `buildinfo` extension)`1` (enabled)**enableAdditionalInfo**Show additional information like IP address and timestamp`1` (enabled)**enableDebug**Enable debug mode to show detailed error messages`0` (disabled)#### Probe-Specific Settings

[](#probe-specific-settings)

SettingDescriptionDefault**schedulerMaxMinutesLate**Maximum minutes a scheduler task can be late before failing`10`**solrMaxErrorCount**Maximum number of Solr indexing errors before probe fails`50`### TypoScript Configuration

[](#typoscript-configuration)

Additional settings can be configured via TypoScript:

```
plugin.tx_healthcheck {
    settings {
        # Override background image via TypoScript
        backgroundImage = EXT:your_extension/Resources/Public/Images/custom-background.png
    }
}

```

Probes
------

[](#probes)

Probes are the heart of the healthcheck system. Each probe checks a specific aspect of your TYPO3 installation and reports whether it's functioning correctly.

### Core Probes

[](#core-probes)

These probes are always available and check fundamental TYPO3 system components.

#### Database Connection

[](#database-connection)

**Class**: `DatabaseProbe`
**Title**: Database Connection
**Always Active**: Yes

Checks if the TYPO3 application can connect to all configured databases.

**What it checks:**

- All database connections defined in your configuration
- Basic query execution capability
- Connection availability

**Fails when:**

- Any database connection cannot be established
- Query execution fails on any connection

---

#### Cache System

[](#cache-system)

**Class**: `CacheProbe`
**Title**: Cache System
**Always Active**: Yes (except in Development context)

Verifies that all configured caches are writable and functioning correctly.

**What it checks:**

- All configured cache backends
- Write and read operations for each cache
- Cache backend availability

**Fails when:**

- Any cache cannot be written to
- Any cache backend is misconfigured
- Cache operations fail

**Note**: This probe is automatically disabled in Development context as development systems often have caching disabled.

---

### Extension-Specific Probes

[](#extension-specific-probes)

These probes require specific TYPO3 extensions to be installed and activated.

#### Scheduler Tasks

[](#scheduler-tasks)

**Class**: `SchedulerProbe`
**Title**: Scheduler Tasks
**Requires**: EXT:scheduler

Monitors TYPO3 scheduler tasks for failures and delays.

**What it checks:**

- Failed scheduler tasks
- Tasks that are significantly delayed (configurable via `schedulerMaxMinutesLate`)
- Task execution status

**Fails when:**

- Any scheduler task has a failure status
- Tasks are running later than the configured maximum delay

**Configuration**: Set `schedulerMaxMinutesLate` in extension configuration to adjust delay tolerance (default: 10 minutes).

---

#### Solr Core Connectivity

[](#solr-core-connectivity)

**Class**: `SolrCoreProbe`
**Title**: Solr Core Connectivity
**Requires**: EXT:solr

Tests connectivity to all configured Solr cores across all site languages.

**What it checks:**

- Connection to each configured Solr core
- Solr server availability
- Core accessibility for each language

**Fails when:**

- Cannot connect to any configured Solr server
- Any Solr core is unreachable
- Solr ping request fails

**Configuration**: Reads Solr configuration from site configuration (host, port, path, core, scheme).

---

#### Solr Index Errors

[](#solr-index-errors)

**Class**: `SolrIndexErrorProbe`
**Title**: Solr Index Errors
**Requires**: EXT:solr

Monitors the Solr indexing queue for errors that prevent content from being indexed.

**What it checks:**

- Number of items in the Solr index queue with errors
- Error count against configured threshold

**Fails when:**

- Number of index errors exceeds `solrMaxErrorCount`

**Configuration**: Set `solrMaxErrorCount` in extension configuration to adjust error tolerance (default: 50 errors).

---

#### External Import

[](#external-import)

**Class**: `ExternalImportProbe`
**Title**: External Import
**Requires**: EXT:external\_import

Checks the status of the latest External Import extension log entry to detect import failures.

**What it checks:**

- Latest import log entry status
- Import success/failure state

**Fails when:**

- Latest import log entry has a non-zero (error) status

---

#### Mailjet Email Delivery

[](#mailjet-email-delivery)

**Class**: `MailjetDeliveryProbe`
**Title**: Mailjet Delivery Success Rate
**Requires**: EXT:mailjet

Monitors email delivery success rate from the Mailjet extension, analyzing emails sent in the last 24 hours.

**What it checks:**

- Total number of emails sent in the last 24 hours
- Number of failed email deliveries
- Failure rate percentage

**Behavior:**

- **No emails**: Reports success if no emails were sent
- **Low volume** (< 10 emails): Reports error only if ALL emails failed
- **Normal volume** (≥ 10 emails): Calculates failure rate percentage
    - ≥ 20% failure rate: **Critical** error
    - ≥ 5% failure rate: **Warning** error
    - < 5% failure rate: Success

**Fails when:**

- All emails in low-volume scenarios failed
- Failure rate ≥ 5% in normal-volume scenarios
- Cannot access the email log database table

**Database**: Queries `tx_mailjet_domain_model_emaillog` table for delivery statistics.

**Thresholds:**

- Time window: 24 hours (86,400 seconds)
- Minimum sample size: 10 emails
- Warning threshold: 5% failure rate
- Critical threshold: 20% failure rate

---

#### SAML Metadata Expiration

[](#saml-metadata-expiration)

**Class**: `SamlMetadataExpirationProbe`
**Title**: SAML Metadata Expiration Probe
**Requires**: SimpleSAMLphp with metarefresh module

Checks SimpleSAMLphp SAML metadata expiration to ensure federation metadata remains valid.

**What it checks:**

- Metadata expiration timestamp from SimpleSAMLphp metarefresh configuration
- Time remaining until metadata expires
- Whether metadata has already expired

**Fails when:**

- Metadata has expired (expiration timestamp is in the past)
- Metadata will expire within the tolerance window

**Configuration:**

- **Environment variable**: `SIMPLESAMLPHP_CONFIG_DIR` must point to SimpleSAMLphp config directory
- **Config files**: Looks for `config-metarefresh.php` or `module_metarefresh.php`
- **Metadata file**: Reads from `saml20-idp-remote.php` in the metarefresh output directory
- **Tolerance**: 30 minutes before expiration (configurable via constant)

**Requirements:**

- SimpleSAMLphp must be installed and configured
- `SIMPLESAMLPHP_CONFIG_DIR` environment variable must be set
- Metarefresh module must be active with valid configuration
- Output directory must use absolute paths

**Note**: This probe automatically activates only if SimpleSAMLphp metarefresh configuration is detected with a valid expiration timestamp.

---

### Creating Custom Probes

[](#creating-custom-probes)

You can easily create your own probes to check specific aspects of your TYPO3 installation.

#### Step 1: Implement the ProbeInterface

[](#step-1-implement-the-probeinterface)

Create a new PHP class that implements the `ProbeInterface`:

```