Laravel Health Check Laravel Package

Technical Evaluation

Architecture fit. This package targets a genuinely underserved seam: health checking for Laravel running on AWS Lambda via Bref. Most established health-check tooling (spatie/laravel-health, Laravel's built-in /up, generic probe libraries) assumes a long-lived host with a persistent filesystem, a writable storage/ path, and background processes to observe. None of that holds on Lambda, where each invocation is an isolated container with an ephemeral /tmp, a read-only code layer, and dependencies resolved at cold start. A Bref-aware check that validates the actual runtime contract — required PHP extensions, /tmp writability, config/route cache validity, cache and database reachability, SSM/Secrets retrieval — is the right shape of solution. The fit is narrow (only relevant if you run Laravel on Lambda with Bref) but high within that boundary.

Integration feasibility. Mechanically trivial: a Composer require, service provider registration, optional config publish, and a route. A competent Laravel engineer can evaluate it in an afternoon. The blocker is not effort, it is information: the README excerpt is a single sentence plus a screenshot, so the actual check inventory, response schema, status-code semantics, and configuration surface are all unknown until we read the source.

Technical risk. Three material concerns. First, validation: one star and zero dependents means no production field data, no third-party write-ups, no Stack Overflow corpus — we would be an early adopter of unproven semantics. Second, coupling: the README states the package is "meant to work with bref.cloud," which suggests the primary supported path runs through Bref's commercial offering rather than raw Bref plus AWS-native monitoring; that is a vendor-coupling question with procurement implications. Third, value density: a health endpoint is 30–80 lines of routing and checks. Adopting a dependency for it is only justified if the package encodes non-obvious Lambda-specific checks we would get wrong ourselves. Also note the security dimension — health endpoints routinely leak PHP version, Laravel version, extension lists, and dependency reachability, all useful reconnaissance.

Key questions.

• Which checks ship out of the box, and are they read-only (no state mutation, no /tmp writes that consume ephemeral storage)?
• Does it require bref.cloud, or does it work standalone with self-managed Bref, ALB, and API Gateway health checks?
• What is the supported matrix — Laravel 10/11/12, PHP 8.2/8.3/8.4, Bref v2.x, API Gateway HTTP API vs. REST API vs. ALB vs. Function URL?
• What are the response contracts — status codes, JSON schema, per-check timeouts, total budget?
• How is the endpoint secured/disabled per environment, and is it excluded from auth, CSRF, session, and rate-limiting middleware by default?
• Who maintains it, what is the release cadence, and is there a stated support commitment or is it a best-effort side project of the Bref org?

Integration Approach

Stack fit. Only proceed if the application is Laravel on AWS Lambda via Bref. If the estate is ECS, Fargate, Forge, Vapor, or EC2, this package is out of scope and the standard health-check options remain correct. Confirm whether the target is bref.cloud (managed) or self-managed Bref before scoping, because that changes both the integration steps and the support path.

Migration path. Greenfield addition, not a migration. Laravel already exposes /up; the decision is whether this package supplements or replaces it. Run both in parallel during evaluation, diff the outputs on the same function, and only retire /up once the new endpoint is proven to cover at least the same ground with Lambda-specific additions.

Compatibility. Verify Composer constraints against our locked Laravel and PHP versions before any code is written. Check how the route is registered — if it is auto-registered in the service provider, we cannot easily gate it behind environment flags or middleware groups without config. Confirm behaviour against our specific compute front end (ALB target group health check vs. API Gateway vs. CloudFront origin), since timeout ceilings and accepted status codes differ. Ensure the endpoint does not boot the full HTTP kernel with session, queue, and event stack, which would inflate cold-start duration precisely on the path that must be fastest.

Sequencing.

1. Source review and README gap analysis — enumerate the checks, confirm read-only behaviour.
2. Spike in a non-production Lambda function; measure cold-start cost of the endpoint versus a no-op route.
3. Gate access: private networking, ALB-only, or a shared secret header; strip it from public route listings.
4. Wire to one consumer only (bref.cloud dashboard or ALB health check or synthetic monitor) to keep failure attribution clean.
5. Define alert thresholds and who is paged.
6. Promote to staging, soak for two weeks, then production.
7. Decide the exit condition up front: if the package proves thin, vendor a fork into the application codebase rather than carrying the dependency.

Operational Impact

Maintenance. MIT licence, small surface, and the Bref organisation's involvement are positives. The bus factor is the concern: a package with one star and no dependents has no downstream pressure to keep it current against Laravel or Bref major versions. Pin the exact version, watch the repository for release cadence, and assume we may need to fork — the code volume is likely small enough that forking is a maintenance non-event.

Support. There is no community support corpus. Escalation is GitHub issues or Bref's community channels, with commercial leverage only if we are bref.cloud customers. Plan for internal ownership: whoever integrates it also owns it.

Scaling. Health checks scale with frequency × function count, not with traffic, and Lambda bills per invocation. A one-minute probe across twenty functions is 28,800 billed invocations per month — negligible in cost but non-zero, and worse, frequent pings can keep functions warm in a way that masks true cold-start behaviour and skews capacity assumptions. Watch for concurrency: a monitoring system that fans out probes during an incident can amplify load on the database and cache precisely when they are already degraded.

Failure modes.

• False negatives: cold-start latency exceeding the ALB or API Gateway timeout causes healthy functions to be deregistered or flagged. Set the check's timeout budget well inside the consumer's threshold.
• False positives: each invocation only probes its own container. A green result from one container says nothing about the fleet — this is a per-invocation self-test, not a fleet health signal, and treating it as the latter is the most likely operational misuse.
• Cascading checks: if the endpoint asserts database and cache reachability under every probe, it becomes a load source and can convert a partial dependency degradation into a full outage via aggressive alerting.
• State mutation: checks that write to /tmp to prove writability consume ephemeral storage per container and can interact badly under repeated invocation.
• Information disclosure: version and extension data on an unauthenticated public route.

Ramp-up. Low for a Laravel developer (hours), moderate for the platform team, who must internalise that this is a runtime contract validator rather than a load balancer-grade availability probe, and configure alerting accordingly. Budget roughly a day of SRE time for access control, alert thresholds, and documenting the per-container semantics so on-call does not misread a green dashboard during a partial outage.