Weave Code
Lib Health Check Laravel Package
oat-sa/lib-health-check
A PHP library from OAT SA for adding health checks to applications. It provides a simple framework for defining checks, aggregating results, and exposing service status for monitoring and readiness or liveness probes.
oat-sa/lib-health-check is a lightweight PHP library for exposing health-check status from applications and services. It helps assemble reusable checks and report whether critical dependencies and runtime conditions are healthy, making it suitable for readiness/liveness probes and monitoring integrations.
- Composable health checks for application dependencies
- Clear status reporting for healthy/unhealthy states
- Framework-agnostic PHP API
- Easy integration with HTTP endpoints and monitoring tools
- Extensible design for custom checks
Frequently asked questions about Lib Health Check
- What is oat-sa/lib-health-check used for?
- It is a PHP library from OAT SA for defining and running health checks against the services your application depends on, then reporting a consolidated status. You use it to express checks as reusable units so monitoring endpoints, readiness probes, and operational dashboards can share the same logic. It is framework-agnostic PHP rather than a Laravel-only package, so you wire it into your app yourself.
- How do I install oat-sa/lib-health-check with Composer?
- Install it with composer require oat-sa/lib-health-check and let Composer resolve the matching version for your PHP constraint. Because the package is distributed through Composer, you should confirm the exact version constraint and any peer requirements in its README or composer.json before committing the lock file. If you are on a private registry setup, make sure the repository is reachable from your CI environment.
- Does oat-sa/lib-health-check work with Laravel?
- Yes, but it is not a Laravel-first package, so there is no auto-discovered service provider or config file to publish. In practice you bind the check runner and your check implementations in a service provider, then invoke them from a controller or Artisan command. Any Laravel version that satisfies the package's PHP requirement can host it, since the integration code is yours.
- How do I create a custom health check with this library?
- You implement a check class that encapsulates the probe logic and returns a status the library can aggregate, following whatever interface the package defines in its source or README. Keep each check small and single-purpose, for example one for the database, one for a queue, and one for an external API, so failures are easy to attribute. Check classes can receive their dependencies through the constructor, which makes them straightforward to resolve from Laravel's container.
- Can I run these health checks from an Artisan command or scheduler?
- Yes. Register a custom Artisan command that resolves the check runner from the container, executes the registered checks, and maps the result to an exit code so cron and your scheduler can react to failures. You can then schedule it with the Laravel scheduler and alert on non-zero exits. This pattern also gives you a simple way to run the same checks in CI smoke tests.
- How do I expose health status over HTTP for Kubernetes or a load balancer?
- Add a route that runs the checks and returns a JSON payload plus an appropriate HTTP status, typically 200 when everything is healthy and 503 when a critical check fails. Decide explicitly which checks are liveness versus readiness so a slow dependency does not restart your pods unnecessarily. The library's status reporting gives you the raw result; shaping the response format is application code.
- What PHP versions does oat-sa/lib-health-check support?
- The supported PHP range is declared in the package's composer.json, so check that file or the Packagist page rather than assuming a version. If your application is on a newer PHP release than the package advertises, verify it in a branch before upgrading production. Pinning to a known-good version in composer.json avoids surprises when a new release changes the minimum PHP requirement.
- Is it safe to run health checks on every request in production?
- Generally no. Checks that hit a database, cache, or remote service add latency and load, so expose them on a dedicated endpoint or scheduled command that your monitoring calls at a sensible interval. Cache the aggregated result briefly if multiple probes or load balancers call it frequently. Also make sure each check has a timeout so a hanging dependency cannot tie up PHP workers.
- How do I test my health checks in a Laravel test suite?
- Because checks are ordinary classes, you can unit test them by injecting fake dependencies, such as a mocked HTTP client or an in-memory database connection, and asserting the resulting status. Then add a feature test that hits your health route and asserts the status code and JSON shape for both the healthy and failing cases. Avoid asserting on real network calls in tests; simulate failures instead so the suite stays fast and deterministic.
- How does it compare to Spatie Laravel Health or Laravel's built-in health route?
- Spatie Laravel Health and Laravel's own health endpoint are Laravel-native, with auto-discovery, config files, and ready-made checks, so they need less glue code in a Laravel app. oat-sa/lib-health-check is a general PHP library, which makes it a better fit if you share health-check logic with non-Laravel services or an existing TAO-based codebase. If you are Laravel-only and want the shortest path, the Laravel-specific options are usually less work.
Weaver
How can I help you explore Laravel packages today?