PHPackages philiprehberger/laravel-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. philiprehberger/laravel-healthcheck ActiveLibrary[Logging & Monitoring](/categories/logging) philiprehberger/laravel-healthcheck =================================== Configurable health check endpoint with built-in checks and Kubernetes probe support v1.1.4(1mo ago)15[2 PRs](https://github.com/philiprehberger/laravel-healthcheck/pulls)MITPHPPHP ^8.2CI passing Since Mar 9Pushed 1mo agoCompare [ Source](https://github.com/philiprehberger/laravel-healthcheck)[ Packagist](https://packagist.org/packages/philiprehberger/laravel-healthcheck)[ Docs](https://github.com/philiprehberger/laravel-healthcheck)[ RSS](/packages/philiprehberger-laravel-healthcheck/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (9)Versions (7)Used By (0) Laravel Healthcheck =================== [](#laravel-healthcheck) [![Tests](https://github.com/philiprehberger/laravel-healthcheck/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/laravel-healthcheck/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/0f49c1a3f4bd09f7800a3f91305c8c5e38f77c5738b6dee620575d24b4de25ba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f6c61726176656c2d6865616c7468636865636b2e737667)](https://packagist.org/packages/philiprehberger/laravel-healthcheck)[![License](https://camo.githubusercontent.com/139670633ec914ecf6243891dcc06a230da279e92b04d9acd2986125bc17d348/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7068696c69707265686265726765722f6c61726176656c2d6865616c7468636865636b)](LICENSE) Configurable health check endpoint with built-in checks and Kubernetes probe support. ### Features [](#features) - Drop-in health check endpoint at `/health` (configurable prefix) - Kubernetes liveness (`/health/live`) and readiness (`/health/ready`) probes - Built-in checks: database, cache, storage, Redis, queue, environment, HTTP - Pluggable: implement `HealthCheck` to add your own checks - Per-check timeout with graceful critical fallback - Optional result caching to reduce backend load - Configurable middleware and route prefix - Full test suite, PHPStan level 8, Laravel Pint enforced Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11 or 12 Installation ------------ [](#installation) ``` composer require philiprehberger/laravel-healthcheck ``` Laravel's package auto-discovery registers the service provider automatically. ### Publishing the config [](#publishing-the-config) ``` php artisan vendor:publish --tag=healthcheck-config ``` This creates `config/healthcheck.php`. Usage ----- [](#usage) ### Basic health check [](#basic-health-check) Once installed, the following endpoints are immediately available: EndpointDescription`GET /health`Full report — `200` if healthy, `503` if not`GET /health/live`Liveness probe — always `200``GET /health/ready`Readiness probe — `200` if healthy, `503` if notExample response from `GET /health`: ``` { "status": "ok", "duration_ms": 14.52, "checks": [ { "name": "database", "status": "ok", "message": "Database connection is healthy.", "meta": { "connection": "mysql" } }, { "name": "cache", "status": "ok", "message": "Cache is healthy.", "meta": [] }, { "name": "environment", "status": "ok", "message": "Environment configuration looks healthy.", "meta": { "env": "production", "debug": false } } ] } ``` When any check is **critical** or **warning**, the overall `status` reflects that and the HTTP status code becomes `503`. ### Status levels [](#status-levels) LevelMeaning`ok`Check passed`warning`Non-fatal issue (e.g. debug enabled)`critical`Check failed — affects readinessThe overall report status is `critical` if any check is critical; `warning` if any is warning and none is critical; `ok` only if all checks are ok. ### Configuration [](#configuration) `config/healthcheck.php`: ``` return [ 'route_prefix' => env('HEALTHCHECK_ROUTE_PREFIX', 'health'), 'middleware' => [], 'checks' => [ \PhilipRehberger\Healthcheck\Checks\DatabaseCheck::class, \PhilipRehberger\Healthcheck\Checks\CacheCheck::class, \PhilipRehberger\Healthcheck\Checks\StorageCheck::class, \PhilipRehberger\Healthcheck\Checks\EnvironmentCheck::class, ], 'timeout' => (int) env('HEALTHCHECK_TIMEOUT', 5), 'cache' => [ 'enabled' => (bool) env('HEALTHCHECK_CACHE_ENABLED', false), 'ttl' => (int) env('HEALTHCHECK_CACHE_TTL', 30), ], ]; ``` #### Restricting access with middleware [](#restricting-access-with-middleware) ``` 'middleware' => ['auth:sanctum'], ``` Or use a custom IP-allowlist middleware for infrastructure-only access. #### Enabling result caching [](#enabling-result-caching) To avoid hammering your database on every probe poll: ``` HEALTHCHECK_CACHE_ENABLED=true HEALTHCHECK_CACHE_TTL=30 ``` ### Built-in checks [](#built-in-checks) #### DatabaseCheck [](#databasecheck) Tests that a PDO connection can be established. ``` new DatabaseCheck() // uses default connection new DatabaseCheck('mysql_reporting') // named connection ``` #### CacheCheck [](#cachecheck) Writes, reads, and deletes a probe key using the default cache driver. Resource cleanup is guaranteed — the probe key is always removed via `try-finally`, even if cache operations fail. #### StorageCheck [](#storagecheck) Writes, reads, and deletes a probe file on the default filesystem disk. Resource cleanup is guaranteed — the probe file is always deleted via `try-finally`, even if read or content verification fails. ``` new StorageCheck() // default disk new StorageCheck('s3') // named disk ``` #### RedisCheck [](#redischeck) Calls `PING` on the Redis connection. Returns a warning (not critical) if the Redis extension and Predis are both absent so the check degrades gracefully in environments without Redis. ``` new RedisCheck() // default connection new RedisCheck('cache') // named connection ``` #### QueueCheck [](#queuecheck) Resolves the queue connection from the container to verify connectivity. ``` new QueueCheck() // default connection new QueueCheck('redis') // named connection ``` #### EnvironmentCheck [](#environmentcheck) Returns a **warning** when `APP_DEBUG=true` in a production environment. #### HttpCheck [](#httpcheck) Pings an external URL and verifies the response status code. ``` new HttpCheck('https://api.stripe.com') new HttpCheck('https://api.stripe.com', timeout: 3, expectedStatus: 200, checkName: 'stripe') ``` Register via the service container for constructor-injected checks: ``` // AppServiceProvider::register() $this->app->bind(\PhilipRehberger\Healthcheck\Checks\HttpCheck::class, fn () => new \PhilipRehberger\Healthcheck\Checks\HttpCheck( url: 'https://api.stripe.com', checkName: 'stripe_api', ) ); ``` Then add the class string to `config/healthcheck.php` `checks` array. ### Writing custom checks [](#writing-custom-checks) Implement the `HealthCheck` contract: ``` use PhilipRehberger\Healthcheck\CheckResult; use PhilipRehberger\Healthcheck\Contracts\HealthCheck; class ElasticsearchCheck implements HealthCheck { public function name(): string { return 'elasticsearch'; } public function check(): CheckResult { try { $info = app('elasticsearch')->info(); return CheckResult::ok( $this->name(), 'Elasticsearch is healthy.', ['version' => $info['version']['number']], ); } catch (\Throwable $e) { return CheckResult::critical($this->name(), $e->getMessage()); } } } ``` Register in `config/healthcheck.php`: ``` 'checks' => [ // ... ElasticsearchCheck::class, ], ``` ### Kubernetes probe configuration [](#kubernetes-probe-configuration) #### Deployment manifest [](#deployment-manifest) ``` livenessProbe: httpGet: path: /health/live port: 8080 initialDelaySeconds: 10 periodSeconds: 15 failureThreshold: 3 readinessProbe: httpGet: path: /health/ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10 failureThreshold: 2 ``` **Liveness** (`/health/live`) — always returns `200` as long as PHP-FPM/Octane is alive. Kubernetes will restart the container only if this stops responding, not on application-level failures. **Readiness** (`/health/ready`) — returns `200` only when all health checks pass. Kubernetes removes the pod from load balancer rotation while this returns `503`, enabling zero-downtime deploys during database migrations or cold-start delays. #### Ingress — skip auth middleware on probe endpoints [](#ingress--skip-auth-middleware-on-probe-endpoints) If you add auth middleware globally, exclude the probe paths in your ingress or use a separate middleware group: ``` // config/healthcheck.php 'route_prefix' => 'health', 'middleware' => [], // no auth on probes — protect at the network level instead ``` API --- [](#api) ### `HealthCheck` (Interface) [](#healthcheck-interface) MethodReturn TypeDescription`name(): string``string`Unique check identifier`check(): CheckResult``CheckResult`Execute the check and return a result### `CheckResult` [](#checkresult) MethodDescription`CheckResult::ok(string $name, string $message, array $meta)`Passing result`CheckResult::warning(string $name, string $message, array $meta)`Non-fatal warning`CheckResult::critical(string $name, string $message, array $meta)`Failing resultDevelopment ----------- [](#development) ``` composer install vendor/bin/phpunit vendor/bin/pint --test vendor/bin/phpstan analyse ``` License ------- [](#license) MIT ### Health Score 40 — FairBetter than 88% of packages Maintenance89 Actively maintained with recent releases Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 6 Last Release 54d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger) --- Top Contributors [![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (21 commits)") --- Tags laravelmonitoringhealthhealthcheckkubernetesk8s ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/philiprehberger-laravel-healthcheck/health.svg) ``` [![Health](https://phpackages.com/badges/philiprehberger-laravel-healthcheck/health.svg)](https://phpackages.com/packages/philiprehberger-laravel-healthcheck) ``` ### Alternatives [yadahan/laravel-authentication-log Laravel Authentication Log provides authentication logger and notification for Laravel. 416632.8k5](/packages/yadahan-laravel-authentication-log)[inspector-apm/inspector-laravel Code Execution Monitoring, built for developers. 2332.0M2](/packages/inspector-apm-inspector-laravel)[jackwh/laravel-new-relic Monitor your Laravel application performance with New Relic 112827.2k](/packages/jackwh-laravel-new-relic)[scoutapp/scout-apm-laravel Scout Application Performance Monitoring Agent - https://scoutapm.com 23831.3k](/packages/scoutapp-scout-apm-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)