Laravel Version Endpoint Laravel Package

Product Decisions This Supports

• Deployment verification and release confidence. The package backs a signed endpoint that reports which build is live. That directly supports post-deploy checks ("did the release actually land in this environment?"), canary/blue-green validation, and rollback decisions — decisions that are otherwise made on guesswork or by reading logs.
• Support and incident triage. Knowing the exact version a customer or environment runs shortens root-cause analysis and reduces the "please send us your version" round trip. This is a small enabler for support tooling and internal dashboards, not a platform commitment.
• Security posture as a product decision. The endpoint is intentionally not publicly readable: version strings are a fingerprinting signal that helps attackers target known CVEs. Making version disclosure gated by a shared signature is a deliberate choice worth recording as a decision, because it constrains later ideas like "publish version on a status page or build badge."
• Build vs. buy. The surface area is one route. In-house is a ~50-line controller and trivially viable. The package is buying hardened edge-case behavior (uniform 404 semantics, signature-before-throttle ordering), not capability. Treat it as a low-commitment convenience, not architecture.
• Roadmap relevance: low but non-zero. If the roadmap includes status pages, public health signals, or externally visible build metadata, this package's signed-only model will need revisiting — plan for a separate mechanism rather than bending this one.
• v0.2.1 specifically is a hardening release with observable behavior changes. Unsigned requests now return the router's standard 404 (matching the framework's own not-found JSON, status, and headers) instead of an empty message; only signed GET/HEAD succeed; OPTIONS no longer answers 200 with Allow, and other methods now answer 404 rather than 405. Most importantly, signature verification now runs before the rate limiter, so anonymous traffic no longer consumes the allowance of a signed caller sharing its IP, receives no rate-limit headers or 429, and no longer touches the cache store. That last item is a real reliability fix for anyone whose monitoring probes sit behind shared NAT or a common egress IP — previously, unrelated internet noise could throttle legitimate version checks and cause false alerts.

When to Consider This Package

Adopt it when:

• You run a Laravel application (confirm the package's supported Laravel/PHP matrix against your version before committing) and you want a version signal consumable by automation.
• Your consumers are trusted systems — CI/CD pipelines, synthetic monitors, internal dashboards, on-call runbooks — that can hold a shared signing secret.
• You want the version endpoint to be indistinguishable from a nonexistent route to anyone without the secret. v0.2.1 makes this the default behavior and is the reason to prefer this release over v0.2.0.
• You need version only, and are content with GET/HEAD semantics. No configuration changes are required to pick up the v0.2.1 behavior.

Look elsewhere — or build in-house — when:

• You need a publicly readable version or build badge (status pages, public "what's deployed" widgets). The signed-only model is the point; don't fight it.
• You need real health checks (database, cache, queue, disk, external dependencies). That is a different concern; use Laravel's built-in health route or a dedicated health package instead of stretching a version endpoint.
• You need per-consumer keys, rotation policy, or audit trails on who read the version. The shared-secret model here is coarse.
• Your edge/CDN terminates or rewrites routes, or your synthetic monitoring tooling probes with OPTIONS for capability discovery — v0.2.1 now answers 404 there, which is deliberate but may look like an outage to naive checks.
• You require stable semantics under a 1.x contract. This is 0.2.x; the patch bump alone changed response codes for OPTIONS and unsigned requests. Pin the version and read changelogs before upgrading.

Two known limitations to accept explicitly, neither blocking: a method the router does not recognize still returns 405 rather than 404 (closing it needs middleware the package does not install), and in applications with a custom fallback route, a missing path is served by that fallback while an unsigned request to the endpoint still gets the exception handler's 404 — so the two can differ per method. Do not build client logic that assumes byte-identical responses between a missing route and an unsigned probe; treat 404 as "unavailable," which is true either way. The payload remains behind the signature regardless.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk capability that answers a question every release process stumbles on — "what version is actually running in this environment?" — without publishing that information to the internet, where version strings help attackers pick targets. The new release tightens it: unauthenticated callers now get the same response as a page that doesn't exist, so the endpoint no longer advertises itself. Effort is measured in hours, not sprints, and it is easily replaced if our needs grow.

For engineering: v0.2.1 is a security and reliability hardening of the endpoint. Three changes matter. First, unsigned requests are now funneled through the framework's own not-found exception, so status, JSON body, and headers match a genuinely missing route instead of returning an empty message — this removes an enumeration signal. Second, the route is registered for every method the router knows, and anything other than a signed GET or HEAD returns 404; previously OPTIONS returned 200 with an Allow header and other methods returned 405, both of which leaked the route's existence. Third, and most operationally relevant: signature verification now runs before the throttle. Unsigned traffic no longer receives rate-limit headers or 429s, no longer touches the cache store, and can no longer exhaust the allowance of a signed caller behind the same client address — which fixes a realistic false-alarm path for monitoring probes sharing a NAT or egress IP. Signed requests are still throttled per the existing throttle setting, and no configuration changes are needed.

Upgrade notes and caveats: despite the patch version, this is behaviorally observable — any test asserting 405 or OPTIONS 200 must be updated. Two limitations remain by design: methods outside the router's known set still return 405 (fixing that needs middleware ahead of the router, which the package does not install), and applications with their own fallback route will answer a missing path via that fallback while an unsigned request to the endpoint returns the handler's 404, so responses can differ per method. Neither exposes the payload. Given we are pre-1.0, pin the version and review changelogs on each bump.