Laravel Caffeine Laravel Package

Product Decisions This Supports

• Feature prioritization by measurable outcome: Session expiry mid-form is a silent conversion killer. Laravel Caffeine converts an invisible reliability bug into a solvable one — it keeps the session and CSRF token alive while a user has a page open, so a completed form actually submits. For a PM, this is a lever on form completion rate, checkout/application abandonment, and support ticket volume, and those are the metrics to attach to the initiative rather than "add a middleware."
• Build vs. buy: The behavior sounds trivial ("ping a route every few minutes"), but the cost lives in edge cases — interval tuning against session.lifetime, middleware and route registration, CSRF interaction, backgrounded tabs, CSP and full-page-cache conflicts, and non-HTML response handling. A well-scoped dependency removes a recurring, hard-to-reproduce bug class from the backlog for the price of a small library. Buying is the default; building is justified only if you already have a session-refresh mechanism or unusual security constraints.
• Roadmap and upgrade sequencing: 13.0.0 is a framework-compatibility release — Laravel 13 support plus a missing Route facade import fix. It is not a feature release. That means it belongs as a rider on the Laravel 13 upgrade programme, not as a standalone initiative competing for roadmap capacity. Decide the team's framework upgrade cadence, and this dependency follows automatically.
• Version-pinning policy as an operating rule: Because the package major tracks the Laravel major, the rule is encodable in an upgrade runbook: match package major to app Laravel major (e.g. ^12.0.3 on Laravel 11/12, ^13.0 on Laravel 13). Pin explicitly so a routine composer update cannot drag the framework forward unexpectedly mid-sprint.
• Scope discipline as a positive signal: The release shipped only two changes — a compatibility bump and a one-line import fix. For a utility dependency, low churn means low re-test and re-certification cost each cycle. That is a good signal for a roadmap that cannot absorb dependency surprises, and it argues for keeping the integration thin so replacement stays a contained effort.
• Knowing where not to spend: If the product is a stateless API, a SPA with client-side token refresh, or if session lifetime already comfortably exceeds realistic task duration, this adds a polling endpoint and configuration surface for no user-visible gain. Make that a deliberate "skip" decision rather than an accidental default.

When to Consider This Package

Adopt when:

• You have authenticated, server-rendered forms that users plausibly hold open longer than session.lifetime (Laravel default: 120 minutes) — wizards, multi-step onboarding, long applications, editors, uploads, complex settings screens, admin data entry.
• You are seeing, or expecting, reports of "randomly logged out," lost drafts, or 419 Page Expired errors on submit for those surfaces.
• You want a framework-idiomatic fix with no new infrastructure — no Redis, no queue worker, no SPA rewrite, no schema changes, no migrations.
• You are on, or planning, Laravel 12/13 and need the dependency to survive that upgrade with a supported release.
• Your team has limited appetite to own and maintain a custom keep-alive implementation and its edge cases.

Look elsewhere or skip when:

• The product is a stateless API or SPA where session lifetime is managed client-side or via token refresh — the premise does not apply.
• You need real draft persistence. Caffeine extends the session; it does not save unsaved form state. If users must recover work after a crash, tab close, or device switch, that is a separate product feature, not this package.
• Session lifetime is already generous relative to real task duration — the added config and polling endpoint are pure overhead.
• You require a large maintainer base or commercial support. This is effectively a single-maintainer project; weigh bus-factor into the build-vs-buy call, and keep the integration small enough that replacing it is a contained effort rather than a migration.

Validate before committing:

• Version constraint: confirm whether 13.0.0 requires Laravel 13 or widens support to 11/12. If it requires 13, this is a rider on the framework upgrade, not a standalone bump. Confirm the minimum PHP version too.
• CSP and caching: the injected inline script must not be blocked by Content-Security-Policy, and full-page caches/CDNs must exclude responses carrying it. Both failure modes are silent — pages still render.
• Session driver parity: verify on the production session driver, not local file. Store expiry semantics differ and this is the most common place a middleware like this behaves differently than in dev.
• Noise control: exclude the keep-alive route from analytics, tracing, and error budgets so it does not skew usage metrics or trigger false alerts.
• Load: one extra request per interval per open page, each writing to the session store. Check session-store headroom before enabling globally on high-traffic anonymous pages.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk dependency that fixes a specific, expensive failure: users losing work when their session expires mid-form. That failure surfaces as abandoned checkouts and applications, "Page Expired" errors, and support tickets — all costly and hard to diagnose after the fact. Version 13.0.0 is a maintenance release adding Laravel 13 support plus a small routing fix; there are no behavior changes and no migration work beyond aligning the package major to our framework major. Recommendation: adopt (or retain), pin the version explicitly, and scope enablement to our long-form surfaces. The only residual risk is single-maintainer bus factor, mitigated by keeping the integration thin, version-pinned, and cheap to replace.

For engineering: Treat this as a small, single-responsibility middleware: it injects a keep-alive snippet into HTML responses and exposes a lightweight GET /caffeine endpoint returning 204 that refreshes the session so CSRF validation succeeds on submit. Integration is hours, not sprints. Register the middleware, publish the config, derive the expiration value from session.lifetime rather than a hardcoded default so the two cannot drift, and confirm the route registers correctly (the 13.0.0 Route facade import fix is relevant if you have customized published assets). Three gates before enabling: CSP must permit the script (nonce/hash/external-script option), no full-page cache may store a response carrying it, and the keep-alive route must live in the same session/auth domain as the forms. Verify on the production session driver. Then sequence: pin the dependency now (immediate, reversible, no behavior change), qualify Laravel 13 separately, and enable per route group behind a feature flag — keep the two changes independently revertible so a rollback of one does not force a rollback of both. Add monitoring on 4xx rates for the keep-alive route before the first production rollout, because the failure mode is silent: forms still render, and users only discover the problem when they lose their work. Finally, assign a named owner for version tracking so this dependency appears on every future framework upgrade checklist.