Actuator Bundle Laravel Package

Getting Started

• Read the framework mismatch first. symsensor/actuator-bundle is a Symfony bundle, not a Laravel package. It relies on Symfony's Bundle class, DI compiler passes, and Symfony routing. Do not composer require it into a Laravel app expecting it to work; Laravel will not discover or boot it. v1.1.0 does not change this — it only widens framework support.
• Check your Symfony version before anything else. v1.1.0 adds Symfony 7.0 compatibility (PR #1). If you are on Symfony 6.x you are still served by the v1.0.x line, but pin deliberately: ^1.1 if you run Symfony 7, and confirm your PHP version satisfies Symfony 7's floor (PHP 8.2+). Run composer why-not symfony/framework-bundle 7.0 if resolution stalls — the constraint conflict is almost always in this bundle's transitive requirements, not your app.
• Where to look: the GitHub README for install/config, then src/ for the health indicator contract (likely HealthIndicatorInterface), the bundle extension class, and the controller that exposes the actuator route. Confirm the default endpoint path (often /actuator/health or a configurable equivalent) and the JSON response shape.
• Minimal Symfony setup if you maintain a Symfony service: composer require symsensor/actuator-bundle:^1.1, let Flex register the bundle (or add it to config/bundles.php), register health indicator services with the appropriate DI tag, and configure the endpoint path. On Symfony 7 with Flex, the recipe registration is the step to verify first if the route 404s.
• First use case: expose a single /health JSON endpoint returning {"status":"UP"} or {"status":"DOWN"} for load balancers, Kubernetes liveness/readiness probes, and uptime monitors.
• Day-to-day in Laravel: treat this package as a design reference. Use spatie/laravel-health or build a small HealthController plus a HealthCheck contract. The Symfony 7 bump gives you no new reason to introduce a Symfony kernel into a Laravel app; if you genuinely need this bundle's behavior, run it in a small Symfony 6.4/7.0 sidecar service and point your infrastructure probes at that service.

Implementation Patterns

• Indicator composition. One class per dependency: database, Redis, disk space, queue worker, external HTTP dependency. Each implements the bundle's health indicator contract and returns a status. The actuator aggregates all indicator results into one response. Mirror this in Laravel with a HealthManager that iterates registered checks.
• Service tagging / registration. Symfony collects indicators via a DI tag (e.g., actuator.health_indicator) and a compiler pass. Symfony 7 tightened service/attribute defaults, so re-verify after upgrading that your indicators are still autoconfigured and tagged — a missing tag silently drops a check from the aggregate rather than erroring. In Laravel, replicate with a config array of check classes resolved from the container, or tag them in a service provider's register() method.
• Split liveness from readiness. Liveness should be cheap and dependency-free (process is alive). Readiness can check dependencies and is allowed to be slower. The bundle may expose a single endpoint; if so, add custom routes/controllers to separate the two.
• Deployment workflow. Wire the endpoint into Docker HEALTHCHECK, Kubernetes livenessProbe/readinessProbe with sensible initialDelaySeconds and timeoutSeconds, ALB/ELB target group health checks, and post-deploy smoke tests. A DOWN state must return HTTP 503 so orchestrators act on it.
• Caching pattern. Do not hit downstream services on every liveness ping. Cache readiness results for 5–15 seconds and use an atomic lock to prevent concurrent expensive checks during probe storms.
• Laravel implementation sketch:

  interface HealthCheck { public function check(): HealthResult; }
  
  class HealthManager {
      public function __construct(private array $checks) {}
      public function run(): array {
          return collect($this->checks)->mapWithKeys(
              fn ($c) => [$c::class => $c->check()->toArray()]
          )->all();
      }
  }
  

  Register checks in a service provider, return response()->json($report, $ok ? 200 : 503) from a GET /health route.
• Security pattern. Keep detailed output internal (private ingress/network). Expose only a minimal status publicly. In Symfony use security.yaml access control; in Laravel use middleware, an IP allowlist, or a signed internal token.
• Observability integration. Log check durations and emit metrics (check name, status, latency). This turns the health endpoint into a lightweight dependency monitor rather than a binary up/down signal.

Gotchas and Tips

• Maintenance is thin, not dead. v1.1.0 is the first release since v1.0.1 (December 2023) and consists of a single community PR for Symfony 7 support — no new features, no API changes. Still pin the exact version ("symsensor/actuator-bundle": "1.1.0"), vendor/fork it if it becomes load-bearing, and keep a migration path. For Laravel, prefer maintained alternatives like spatie/laravel-health.
• The upgrade itself is low-risk but test the wiring. The changelog shows compatibility work only, but Symfony 7 removed deprecated APIs around container compilation and routing. Smoke-test after bumping: bundle still registered, route still present (bin/console debug:router | grep -i health), indicators still tagged, and the JSON shape unchanged for anything parsing it.
• Don't assume Symfony 7 means modern everything. The package predates Symfony 7 by years; the PR is a compatibility shim, not a rewrite. Review the diff for the constraints it declares (PHP floor, symfony/* ranges) before assuming it works with Symfony 7.1/7.2 or PHP 8.4.
• Framework mismatch is a hard blocker. Composer may resolve dependencies, but the bundle expects Symfony's kernel, container, and routing. You will get confusing container or bundle-registration errors in Laravel. Use it only in Symfony services.
• HTTP status is the real contract. Probes read status codes, not JSON bodies. Verify the endpoint returns 503 (not 200) when DOWN, and that your ingress/proxy preserves the status. An endpoint that always returns 200 defeats the purpose.
• Timeout everything. DB, Redis, and HTTP checks must have short timeouts (1–2 seconds). A hanging check causes the orchestrator to kill a healthy pod. In Laravel use Http::timeout(2) and a low connection timeout for database checks.
• Avoid probe stampedes. Kubernetes and load balancers can hit /health frequently and concurrently. Cache results and use a lock so expensive checks run once per interval, not once per probe.
• Response leakage. Health payloads can expose DSNs, versions, and internal hostnames. Return only statuses and error codes; log detailed errors server-side.
• Extension points. Custom indicators, custom aggregation/status mapping, and route/config overrides are the intended extension seams. If you fork, keep the indicator contract stable so future syncs are cheap — v1.1.0 did not touch it, which makes forking now relatively clean.
• Debugging. In Symfony, use bin/console debug:container --tag=<indicator-tag> to confirm registration and check var/log/. In Laravel, use php artisan route:list, php artisan about, and duration logs. Add an internal-only ?verbose=1 mode that returns per-check details.
• Config quirks. Endpoint path and enabled state are bundle config; changing the path requires updating every probe definition. If not using Flex, remember to add the bundle to config/bundles.php — on Symfony 7 this is the most common reason the health route disappears after an upgrade.