README

A Symfony bundle providing a /health endpoint to monitor your application and its dependencies.

Installation

composer require lgarret/health-check-bundle

Register the bundle

// config/bundles.php
return [
    // ...
    Lgarret\HealthCheckBundle\HealthCheckBundle::class => ['all' => true],
];

Import routes

# config/routes/health_check.yaml
health_check:
    resource: '@HealthCheckBundle/config/routes.php'

Allow public access

If you use the Symfony SecurityBundle, make sure the health route is publicly accessible:

# config/packages/security.yaml
security:
    access_control:
        - { path: ^/health$, roles: PUBLIC_ACCESS }
        # ...

Configuration

# config/packages/health_check.yaml
health_check:
    path: '/health'                           # Route path (default: /health)
    secret: '%env(HEALTH_CHECK_SECRET)%'      # Optional — token to access detailed results
    header: 'X-Health-Token'                  # Optional — custom header name (default: Authorization)
    timeout: 5                                # Optional — max seconds per check (default: 5)
    cache:
        enabled: true                         # Optional — cache check results (default: true)
        ttl: 300                              # Optional — cache duration in seconds (default: 300)
    checks:
        doctrine: true                        # Optional — auto-register Doctrine DBAL checks (default: true)
        asset_mapper: true                    # Optional — auto-register AssetMapper check (default: true)

Option	Type	Default	Description
`path`	`string`	`/health`	URL path for the health check endpoint.
`secret`	`string?`	`null`	Token expected in the configured header. If `null`, details are never exposed.
`header`	`string`	`Authorization`	Name of the HTTP header used to send the secret token.
`timeout`	`int`	`5`	Maximum execution time in seconds for each individual check.
`cache.enabled`	`bool`	`true`	Enable caching of health check results.
`cache.ttl`	`int`	`300`	Cache TTL in seconds (5 minutes by default).
`checks.doctrine`	`bool`	`true`	Auto-register Doctrine DBAL checks (one per connection) if `doctrine/dbal` is installed.
`checks.asset_mapper`	`bool`	`true`	Auto-register AssetMapper check if `symfony/asset-mapper` is installed.

Usage

`GET /health`

Without auth header (or without a configured secret):

GET /health
→ 200 {"status": "ok"}
→ 503 {"status": "ko"}

With a valid auth header:

GET /health
X-Health-Token: my-secret-token

→ 200 {"status": "ok", "checks": {"database": {"status": "ok"}, "redis": {"status": "ok"}}}
→ 503 {"status": "ko", "checks": {"database": {"status": "ok"}, "redis": {"status": "ko", "error": "Connection refused"}}}

Console command

Run checks from the command line:

bin/console health:check

Health Check
============

 ---------- -------- --------------------
  Check      Status   Error
 ---------- -------- --------------------
  database   ✓ OK
  redis      ✗ KO     Connection refused
 ---------- -------- --------------------

 [ERROR] 1 of 2 check(s) failed.

Built-in checks

The bundle ships with built-in checks that are automatically registered when the corresponding packages are installed:

Check	Package required	What it does
`doctrine`	`doctrine/dbal`	Runs `SELECT 1` on each configured DBAL connection
`asset_mapper`	`symfony/asset-mapper`	Checks that `manifest.json` exists (assets compiled)

Built-in checks are enabled by default and auto-detected via class_exists() and service availability. One check is registered per Doctrine connection (e.g. doctrine_default, doctrine_analytics). The asset mapper check verifies that public/assets/manifest.json exists (i.e. asset-map:compile has been run). You can disable them in your configuration:

health_check:
    checks:
        doctrine: false
        asset_mapper: false

Creating a custom check

Implement HealthCheckInterface — the service will be automatically discovered and registered:

<?php

namespace App\Check;

use Lgarret\HealthCheckBundle\Check\HealthCheckInterface;
use Lgarret\HealthCheckBundle\Dto\HealthCheckResult;
use Doctrine\DBAL\Connection;

class DatabaseHealthCheck implements HealthCheckInterface
{
    public function __construct(private readonly Connection $connection)
    {
    }

    public function getName(): string
    {
        return 'database';
    }

    public function check(): HealthCheckResult
    {
        try {
            $this->connection->executeQuery('SELECT 1');
            return HealthCheckResult::ok();
        } catch (\Throwable $e) {
            return HealthCheckResult::ko($e->getMessage());
        }
    }
}

Flex recipe

Sample configuration files are available in the recipe/ directory for use with Symfony Flex.

Development

composer install
vendor/bin/phpunit          # Run tests
vendor/bin/phpstan analyse  # Static analysis (level max)

License

MIT

lgarret / health-check-bundle

Maintainers

Package info

Statistics

Security