Health Check Bundle Laravel Package

Getting Started

• Check the framework fit before anything else. Despite the generic "health check" name, smartassert/health-check-bundle is a Symfony bundle: read vendor/smartassert/health-check-bundle/composer.json and you'll see symfony/framework-bundle (and likely symfony/routing / symfony/http-kernel) rather than illuminate/support. There is no Laravel service provider, no facade, no publishable config/health-check.php. On Laravel you cannot composer require this into the app and expect it to boot — and 8.2 changed nothing about that.
• If you are on Symfony (the supported target):

  composer require smartassert/health-check-bundle
  

  As of 8.2 the constraint is symfony ^7 || ^8, so the resolver will only pick this release on a Symfony 7/8 app. Register it in config/bundles.php:

  SmartAssert\HealthCheckBundle\HealthCheckBundle::class => ['all' => true],
  

  Then confirm what it actually registered:

  bin/console debug:router | grep -i health
  bin/console debug:config health_check   # if a Configuration class exists
  

• Where to look first, in order: the bundle README.md, src/DependencyInjection/Configuration.php (the only trustworthy source of config keys), src/Controller/ (the response contract), and src/Resources/config/routing.* (whether the route is auto-imported or must be wired manually).
• If you are on Laravel (most likely, given this assessment): treat the package as a reference implementation, not a dependency. Read the controller, copy the contract into routes/web.php or routes/api.php as a 15–30 line closure/controller, and wire it to your existing monitoring. The value is the shape of the endpoint, not the code. The 8.2 release is a dependency-constraint bump only — no new endpoint behaviour to port.
• First use case: point an uptime monitor (Pingdom, UptimeRobot, Better Stack), a load-balancer target-group health check, or a Kubernetes readinessProbe at the route and assert 200 plus the expected JSON body. Nothing else in the package matters until that loop is green.

Implementation Patterns

• Liveness vs. readiness split. Use the bundle's endpoint as a liveness check (process is up, framework booted, route resolves) and do not let it perform slow dependency calls. If the bundle exposes a configurable check list, keep the LB-facing route shallow and add a separate, internal-only deep check for DB/Redis/queue.
• Assert on body, not just status. A health endpoint that returns 200 from a generic exception handler is worse than no endpoint. In your monitor, assert the JSON shape (e.g. status === "ok") and the Content-Type.
• Deployment smoke test. In CI/CD, after php artisan route:list / bin/console cache:clear, boot the app and curl -fsS http://localhost/health before shifting traffic. This is the cheapest place to catch a bundle-registration or route-import regression — and the cheapest place to catch a Symfony-version upgrade that quietly changed the response.
• Custom checks via DI (Symfony). If the bundle defines a check interface, implement it as a tagged service and let the container collect tagged services. This is the extension point to prefer over editing vendor code.
• Laravel translation of the pattern:

  Route::get('/health', fn () => response()->json(['status' => 'ok']))
      ->withoutMiddleware(['auth', 'throttle']);
  

  Keep it outside auth middleware, but bind it to internal networks / a shared secret header if it is publicly reachable.
• Probe configuration. Set timeoutSeconds/periodSeconds conservatively (e.g. 1s/10s) on k8s probes, and set LB health-check interval > app cold-start time, otherwise you'll flap instances during deploy. This matters more on Symfony 7/8, where a cold container/DI cache is noticeably heavier.
• Observability tie-in. Log health-check failures at warning (not error — they're expected during deploys) and emit a metric so you can alert on rate of failure rather than a single blip.

Gotchas and Tips

• Framework mismatch is still the headline gotcha. 8.2 tightens the Symfony coupling rather than loosening it. With 1 star and 0 dependents, there is effectively no community to catch edge cases; combined with the Symfony/Laravel boundary, you are on your own for anything beyond the happy path. Budget for reading source, not docs.
• 8.2 is a constraint-only release, but it moves the floor under you. symfony ^7 || ^8 means: Symfony 7 requires PHP >= 8.2 and Symfony 8 requires PHP >= 8.4. If your app is on Symfony 5.4/6.x, composer require will silently resolve to 8.1 (or fail), and a bare composer update on a mixed monorepo can split versions across services. Check composer why-not smartassert/health-check-bundle 8.2 before blaming the package.
• Pin the version explicitly. The earlier ~1.0-style advice is wrong — this package is on the 8.x line. Use "smartassert/health-check-bundle": "~8.2" or an exact tag. Because 8.2 exists solely to widen a dependency constraint, a loose ^8 is how you accidentally absorb a future release whose only change is a Symfony/PHP floor bump.
• No Laravel integration surface, unchanged in 8.2. No HealthCheckServiceProvider, no mergeConfigFrom, no artisan command. Any attempt to autoload it in Laravel will at best be dead code and at worst pull conflicting Symfony contracts into your vendor/.
• Route collisions and caching. If the bundle auto-imports a route like /health, it can shadow an existing Laravel/Symfony route. After install or upgrade, always debug:router; on Symfony, stale var/cache will keep serving an old route map — cache:clear first when debugging a 404. This is the most common symptom after a major-version jump.
• Config keys are undocumented in the wild. Rely on Configuration.php (or debug:config) rather than blog posts; with a package this small, the config tree may change between minor releases. 8.2 did not touch it, but that is a single data point, not a guarantee.
• Don't let the endpoint do real work. A health check hit every 10s from three LBs is ~26k requests/day; if the implementation touches the DB or hits Redis, you have added a self-inflicted load source and a dependency-coupling failure mode (health check fails → LB removes node → node was actually fine).
• Security exposure. Health endpoints routinely leak versions, environment names, and dependency status. Either restrict by network/middleware, return a bare {"status":"ok"}, or use a separate internal port. Never return stack traces or connection strings from it.
• Status-code semantics matter. Decide deliberately whether a degraded dependency yields 200 (app is alive) or 503 (readiness). Mixing the two causes flapping and confusing on-call pages.
• Extension points to prefer, in order: tagged check services → a small decorator around the controller → forking/vendoring. Do not edit files under vendor/; a composer update will silently revert you, and with a maintainer who ships constraint bumps promptly, updates will keep coming.
• Debugging checklist when the route 404s/500s: (1) bundle registered in bundles.php; (2) routing imported in config/routes.yaml; (3) cache:clear; (4) debug:router; (5) check var/log/dev.log for the actual exception — a 500 on a health route is usually a DI wiring error, not a monitoring problem. After a Symfony 7/8 upgrade, add step (0): confirm the installed bundle version in composer show.
• Longevity risk: slightly improved, not resolved. The 8.2 PR shows the maintainer is actively tracking Symfony majors, which is a genuine positive signal for staying installable. It is still a personal-scale utility with 1 star and 0 dependents, and it is still not a Laravel package. For the ~20 lines of code it provides, porting the endpoint into your own app remains the lower-risk option.