Laravel Etag Middleware Laravel Package

Technical Evaluation

Architecture fit

• A single Laravel HTTP middleware (~1 class + a small config file) that hashes the outgoing response body into an ETag and returns 304 Not Modified when the request's If-None-Match matches. No database, queue, cache backend, or external service — it sits entirely inside the framework's HTTP pipeline.
• Structurally a clean fit: registerable globally in app/Http/Kernel.php or scoped to a route group (api, or specific read-only endpoints). Removal is a one-line revert, which keeps the reversibility cost near zero.
• Important framing for stakeholders: this improves bandwidth and client-perceived latency, not application CPU. The app still renders the full response to compute the hash; the win is that repeat clients skip the payload transfer and re-render/parse work.

Integration feasibility

• Composer-only onboarding, no infrastructure change. A competent Laravel engineer can spike this in half a day including verification.
• Real risk is not integration effort but constraint resolution: the last release is September 2020 (Laravel 5–7 era constraints). On Laravel 10/11/12 the package likely will not resolve without widening constraints, forking, or vendoring the middleware class into the app namespace. MIT license makes vendoring trivial and legally clean.

Technical risk

• Maintenance/supply chain: 64 stars, single maintainer, no release in ~5 years. Treat as unmaintained code you are adopting, not a supported dependency.
• Correctness around caching semantics: ETag must be deterministic per representation. Non-deterministic response content (CSRF tokens, timestamps, debug output, per-user personalization without a correct Vary) can produce incorrect 304s or, worse, shared-cache collisions.
• Response type coverage: streamed responses, BinaryFileResponse downloads, SSE, and responses that already set their own ETag (or that a CDN already tags) are all edge cases the middleware does not reason about by default.
• Duplication of native capability: Laravel responses extend Symfony's Response, which already exposes setEtag() / isNotModified(). The functional delta of this package is small.

Key questions

1. Which Laravel and PHP versions are in scope, and does the package's composer.json resolve without a fork?
2. Which routes are genuinely cacheable/idempotent GETs, and are their bodies byte-stable across requests?
3. Is there already a CDN or reverse proxy issuing ETags? If so, the marginal benefit drops sharply and double-hashing is wasted work.
4. Are there streaming, download, or authenticated-personalized endpoints that must be excluded?
5. Do clients (mobile SDKs, integrators) correctly send If-None-Match and handle bodyless 304s? Any that don't will regress.
6. Strong vs. weak ETag semantics — does anyone downstream care?

Integration Approach

Stack fit

• Pure Laravel middleware; no opinion on hosting, database, or queue. Fits both monolith and API-only deployments. Works alongside response caching but must be sequenced deliberately relative to it.

Build vs. buy

• Recommend a timeboxed spike (≤1 day). If the package resolves and passes the correctness checks below, adopt it as an accelerator. If constraint resolution, forking, or edge-case handling exceeds roughly a day, replace it with ~40–60 lines of in-house middleware wrapping setEtag()/isNotModified() — the team then owns semantics explicitly, which is preferable to owning an abandoned fork.
• Do not position this as a platform dependency. It is a tactical optimization with an exit ramp.

Compatibility and migration path

• Verify constraint resolution first; if blocked, prefer vendoring the middleware class into app/Http/Middleware over an internal fork (smaller long-term surface, no package registry overhead).
• Ship behind a config flag (ETAG_ENABLED) plus explicit route scoping so rollout and rollback are configuration changes, not deploys.

Sequencing

1. Dependency/constraint spike on a branch; decide adopt vs. vendor vs. build.
2. Confirm baseline behavior with curl -I against a single low-risk, read-only GET endpoint: first call 200 + ETag, second call with If-None-Match → 304 and empty body.
3. Enable on one route group in staging; explicitly exclude streaming, download, and personalized endpoints.
4. Canary to a small production slice; watch 304 rate, egress, and error/latency dashboards.
5. Expand to all idempotent GET/HEAD if metrics hold; document the exclusion list and the middleware ordering contract.
6. If a CDN is in front, decide who owns ETag generation — app or edge — and disable the loser.

Operational Impact

Maintenance

• Very low ongoing code volume, but effectively unmaintained upstream: the team owns version-constraint upkeep, PHP 8.x compatibility, and security review of the adopted code. Budget a few hours per Laravel major upgrade; realistically this becomes a vendored file within two upgrade cycles.

Support

• No vendor, no SLA, no upstream responsiveness. Support burden falls to the platform team, mitigated by the tiny blast radius and trivial removal path.

Scaling

• Horizontally neutral: stateless, no shared cache, negligible memory. Cost is one hash pass over each eligible response body — immaterial for typical JSON payloads, noticeable only on multi-megabyte bodies (another reason to exclude large/binary responses).
• Benefit scales with repeat-request rate and payload size: strongest on high-frequency polling APIs and mobile clients on constrained links. Behind a CDN, the edge may already capture most of the gain.

Failure modes

• Incorrect 304 from non-deterministic bodies → clients show stale data; hardest failure to notice because it looks like a cache bug, not an app error.
• Missing or wrong Vary on personalized responses → cross-user cache bleed if a shared cache sits in front.
• Buffering/breaking streamed or binary responses.
• Duplicate ETag headers from app + CDN or app + framework.
• Middleware ordering conflicts with response caching and compression.
• Client regressions where SDKs treat 304 as an error.

Ramp-up

• 1–2 hours for a Laravel-fluent engineer to wire and verify; add a short RFC 7232 conditional-request primer so the team reasons about strong/weak validators correctly.
• Ops/on-call need one explicit note: a rising 304 rate is success, not an error spike — otherwise it will be triaged as an incident during the first rollout.