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)

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:

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());
        }
    }
}

Querying a remote health check endpoint

HealthCheckClient lets you query the /health endpoint of another Symfony application (e.g. a different site running this same bundle) and get back a typed result instead of raw JSON. It requires symfony/http-client:

composer require symfony/http-client

use Lgarret\HealthCheckBundle\Client\HealthCheckClient;

class StatusController
{
    public function __construct(private readonly HealthCheckClient $healthCheckClient)
    {
    }

    public function __invoke(): Response
    {
        $result = $this->healthCheckClient->check(
            url: 'https://other-site.example.com/health',
            secret: 'their-secret-token',
            header: 'X-Health-Token', // optional, defaults to "Authorization"
            timeout: 3.0,             // optional, defaults to 5 seconds
        );

        if (!$result->reachable) {
            // $result->error contains the network/parsing error (timeout, connection refused, invalid response, ...)
        }

        // $result->report is a HealthCheckReport (status + per-check HealthCheckResult), like the local one
    }
}

HealthCheckClient::check() returns a RemoteHealthCheckResult:

If no secret (or an empty string) is provided, the remote endpoint will only return its global status (no checks detail), matching the unauthenticated response documented above.

HealthCheckClient is only registered as a service when symfony/http-client is installed (auto-detected, like the built-in checks). If it isn't installed, autowiring HealthCheckClient fails with Symfony's standard "service not found" error at compile time, rather than a runtime exception.

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