Download the PHP package kiora/health-check-bundle without Composer

Health Check Bundle

A Symfony bundle providing comprehensive health check functionality for monitoring application dependencies and services.

Why use this bundle?

Production-Ready & Battle-Tested

• Comprehensive test coverage with 37 tests and 104 assertions
• PHPStan level 9 static analysis - strictest type safety (maximum level)
• CI/CD pipeline testing across PHP 8.3/8.4 and Symfony 6.4/7.0/7.1
• Security-first design with no sensitive information exposure

Enterprise-Grade Features

• Multiple database connections support (read/write replicas, analytics, logs)
• Context-aware health checks with group filtering (web, worker, console)
• Kubernetes-ready with dedicated liveness (/ping) and readiness (/ready) probes
• Performance monitoring with execution statistics and slow check detection

Developer-Friendly

• Modern auto-configuration with Symfony's #[AutoconfigureTag]
• No manual service tagging required
• Docker development environment included
• Follows Symfony best practices and coding standards

Features

• 🔍 Multiple Health Checks: Database, Redis, S3/MinIO, HTTP endpoints
• 🗂️ Multiple Connections: Support for multiple database connections (read/write replicas, analytics, logs)
• 🏷️ Check Groups: Filter health checks by context (web, worker, console) via ?group= parameter
• 🔒 Security First: No sensitive information exposed (versions, paths, credentials)
• ⚡ Performance: Configurable timeouts, non-blocking checks
• 🎯 Flexible: Critical vs non-critical checks, enable/disable per check
• 🛡️ Production Ready: Rate limiting, security headers, generic error messages
• 📊 Standard Format: JSON response with status, duration, and individual check results
• 📈 Performance Statistics: Monitor slow checks, average execution time, and identify performance bottlenecks

Development with Docker

The project includes a complete Docker environment for development and testing.

Quick Start

Available Services

• PHP 8.4 with all required extensions
• MySQL 8.0 on port 3306
• PostgreSQL 16 on port 5432
• Redis 7 on port 6379
• MinIO (S3-compatible) on ports 9000 (API) and 9002 (Console)

Manual Commands

If you prefer not to use Make:

Installation

1. Install the bundle

2. Enable the bundle

If Symfony Flex is not installed, manually add the bundle to config/bundles.php:

3. Import routes

Create config/routes/health_check.yaml:

4. Configure security access

Add public access to the health check endpoint in config/packages/security.yaml:

5. (Optional) Configure rate limiting

Create config/packages/rate_limiter.yaml:

Install required packages:

Configuration

Basic Configuration

Create config/packages/health_check.yaml:

Built-in Checks

1. Database Check (Auto-registered)

✅ Automatically enabled - Verifies database connectivity using Doctrine DBAL.

No additional configuration needed. Works out of the box with your existing Doctrine configuration.

Multiple Database Connections

If your application uses multiple database connections (e.g., read/write replicas, analytics database, logs database), you can configure separate health checks for each connection:

Naming Convention:

• Default connection: Returns database
• Named connections: Returns database_{name} (e.g., database_analytics, database_logs)

Configuration Options:

• $name: Connection identifier (default: 'default')
• $critical: Whether failure should return HTTP 503 (default: true)
• $groups: Contexts where this check runs (default: [] = all contexts)

2. Redis Check (Manual setup)

⚙️ Disabled by default - Only configure if your project uses Redis.

Step 1: Enable in configuration

Step 2: Configure the service

Create or update config/packages/health_check.yaml:

Step 3: Add environment variables

3. S3/MinIO Storage Check (Manual setup)

⚙️ Requires manual configuration - Only configure if your project uses S3/MinIO storage.

Example for multiple buckets:

4. HTTP Endpoint Check (Manual setup)

⚙️ For monitoring external dependencies - Configure for each external API you depend on.

Example: Microsoft Graph API

Usage

Available Endpoints

The bundle provides three distinct endpoints for different monitoring purposes:

1. /ping - Liveness Probe (Lightweight)

A simple endpoint that verifies the application is running without checking any external dependencies.

Response:

Use case: Kubernetes liveness probes, load balancer health checks

Characteristics:

• Always returns HTTP 200 (unless the app is completely down)
• No database or external service checks
• Extremely fast response time
• Minimal resource usage

2. /ready - Readiness Probe (Critical Dependencies)

Checks if the application is ready to serve traffic by verifying critical dependencies in the "readiness" group.

Response:

Use case: Kubernetes readiness probes, determining when pods should receive traffic

Characteristics:

• Returns HTTP 200 if all critical dependencies are healthy
• Returns HTTP 503 if any critical dependency is unhealthy
• Only checks services in the "readiness" group
• Prevents traffic routing to pods with unhealthy dependencies

3. /health - Comprehensive Health Check

Provides complete health status of all configured health checks, optionally filtered by group.

Use case: Monitoring dashboards, alerting systems, comprehensive health status

Characteristics:

• Returns HTTP 200 if all critical checks pass
• Returns HTTP 503 if any critical check fails
• Supports filtering by group via ?group= parameter
• Includes performance statistics

Endpoint Comparison

Configuring Health Checks for Readiness

To mark health checks as critical for readiness probes, assign them to the "readiness" group:

Response Format

Statistics Breakdown

The statistics section provides performance insights:

• total_checks: Total number of health checks executed
• slow_checks: Number of checks that took longer than 1 second to execute
• average_duration: Average execution time across all checks (in seconds)
• slowest_check: Details of the slowest health check
  • name: Name of the slowest check
  • duration: Execution time in seconds
  • Will be null if no checks were executed

Status Codes

• 200 OK: All critical checks passed
• 503 Service Unavailable: One or more critical checks failed

Check Status Values

• healthy: Check passed successfully
• unhealthy: Check failed
• degraded: Check passed with warnings (reserved for future use)

Filtering Checks by Group

Health checks can be organized into groups/contexts (e.g., web, worker, console) to enable granular monitoring based on the application context.

Using the Group Query Parameter

Filter health checks by group using the ?group= query parameter:

Configuring Groups

Assign groups to health checks in your service configuration:

Group Filtering Behavior

• Empty groups ($groups: []): Check runs in all contexts (no filtering)
• Specified groups ($groups: ['web', 'worker']): Check runs only when requested group matches
• No group parameter: All checks run (default behavior)

Use Cases

Kubernetes Probes:

Console Commands:

Monitoring Different Environments:

Creating Custom Health Checks

1. Create your check class

Simply implement HealthCheckInterface or extend AbstractHealthCheck. No manual tagging required!

2. Register your check

If you have autowire: true and autoconfigure: true in your services.yaml (default in modern Symfony):

How it works: All classes implementing HealthCheckInterface are automatically tagged with health_check.checker thanks to the #[AutoconfigureTag] attribute on the interface. No manual tagging needed!

Configuration Options:

• $critical: Set to true if this check's failure should return HTTP 503 (default: false)
• $groups: Array of group names this check belongs to (default: [] = all groups)

Security Considerations

What's Included ✅

• Generic error messages - No stack traces or internal paths
• No version information - Database/Redis versions not exposed
• No connection details - Hostnames, IPs, credentials hidden
• Security headers - X-Robots-Tag, Cache-Control, X-Content-Type-Options
• Rate limiting support - Prevent abuse and DoS attacks
• Empty metadata - No sensitive information in responses

What's NOT Included ❌

• Database names or connection strings
• Server versions or software versions
• File paths or directory structures
• Exception messages with sensitive data
• Response sizes or client counts
• Internal URLs or endpoints

Best Practices

1. Enable rate limiting to prevent abuse
2. Use IP whitelisting for production environments if possible
3. Monitor access logs to detect reconnaissance attempts
4. Keep checks non-critical unless absolutely necessary
5. Avoid exposing internal service names in check names

Monitoring Integration

Kubernetes Liveness and Readiness Probes

Kubernetes distinguishes between two types of health checks:

• Liveness Probe: Determines if the pod is alive and should be restarted if not
• Readiness Probe: Determines if the pod is ready to receive traffic

Recommended Configuration

Probe Configuration Explained

Liveness Probe (/ping):

• initialDelaySeconds: 10 - Wait 10 seconds after container starts before first check
• periodSeconds: 10 - Check every 10 seconds
• timeoutSeconds: 3 - Consider failed if no response within 3 seconds
• failureThreshold: 3 - Restart pod after 3 consecutive failures
• Uses /ping endpoint which has no external dependencies and is extremely fast

Readiness Probe (/ready):

• initialDelaySeconds: 5 - Wait 5 seconds after container starts before first check
• periodSeconds: 5 - Check every 5 seconds
• timeoutSeconds: 5 - Consider failed if no response within 5 seconds
• failureThreshold: 3 - Remove from service after 3 consecutive failures
• Uses /ready endpoint which checks critical dependencies (database, cache, etc.)

Why Separate Endpoints?

Problem with using /health for both:

Issues:

1. If database is temporarily unavailable, pod gets restarted (liveness)
2. Unnecessary restarts can cause cascading failures
3. No distinction between "app is running" and "app can serve traffic"

Solution with separate endpoints:

Benefits:

1. Database issues remove pod from service (readiness) but don't restart it (liveness)
2. Pod has time to recover from transient failures
3. Clear separation of concerns
4. Follows Kubernetes best practices

Context-Specific Health Checks

For different deployment types, use the ?group= parameter:

Docker Healthcheck

Prometheus/Grafana

The JSON response can be easily parsed and converted to metrics for monitoring dashboards.

Troubleshooting

Health check returns 404

• Verify routes are imported in config/routes/health_check.yaml
• Clear cache: php bin/console cache:clear
• Check bundle is enabled in config/bundles.php

Check always returns "unhealthy"

• Verify service configuration (host, port, credentials)
• Check Docker network connectivity between services
• Review application logs for connection errors
• Ensure the service is actually running

Rate limiting errors

• Install required packages: composer require symfony/rate-limiter symfony/lock
• Configure rate limiter in config/packages/rate_limiter.yaml

Redis check not working

• Ensure Redis service is running
• Verify Redis is on the same Docker network as your application
• Check REDIS_HOST and REDIS_PORT environment variables
• Test connection: docker compose exec php php -r "..."

Requirements

• PHP >= 8.2
• Symfony >= 6.4 or >= 7.0
• Doctrine DBAL (for database check)

Optional Dependencies

• ext-redis: For RedisHealthCheck with PHP Redis extension
• predis/predis: Alternative Redis client
• league/flysystem: For S3HealthCheck
• symfony/http-client: For better HTTP check performance
• symfony/rate-limiter: For rate limiting support
• symfony/lock: Required by rate limiter

Configuration Reference

Complete Example

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Code Quality

This project uses GrumPHP to ensure code quality. All checks are run automatically before each commit:

Coding Standards

• PSR-12: Follow PSR-12 coding standards
• Strict types: All files must declare strict_types=1
• Type hints: Use type hints for all method parameters and return types
• PHPStan Level 8: Code must pass PHPStan level 8 analysis
• Tests: Add tests for new features and bug fixes

Support

• Issues: GitHub Issues
• Documentation: README.md

License

This bundle is released under the MIT License.

Credits

Created and maintained by Kiora Tech.

Changelog

Unreleased

• Readiness Probe Endpoint: Added dedicated /ready endpoint for Kubernetes readiness probes
  • Checks only health checks in the "readiness" group
  • Returns HTTP 200 when ready, 503 when not ready
  • Proper separation between liveness (/ping) and readiness (/ready) probes
  • Follows Kubernetes best practices for probe configuration
  • Prevents traffic routing to pods with unhealthy critical dependencies
• Multiple Database Connections: Support for monitoring multiple Doctrine DBAL connections
  • Named connections with custom identifiers (e.g., database_analytics, database_logs)
  • Per-connection criticality configuration
  • Backward compatible with existing single connection setup
• Health Check Groups: Filter checks by context/group for granular monitoring
  • Query parameter support: ?group=web, ?group=worker, ?group=console
  • Per-check group assignment
  • Empty groups = belongs to all contexts (default behavior)
• Comprehensive test suite with 37 tests and 104 assertions

1.0.0 (2025-11-06)

• Initial open source release
• Database, Redis, S3, and HTTP health checks
• Security-first design with no sensitive data exposure
• Modern auto-tagging with #[AutoconfigureTag] (Symfony 6.1+)
• Rate limiting support
• Configurable timeouts and critical checks
• Enable/disable checks via configuration
• Production-ready with Kubernetes/Docker support