Idle Lock Screen Bundle Laravel Package

Getting Started

tourze/idle-lock-screen-bundle is a Symfony bundle (note the Bundle suffix — it registers via config/bundles.php, not Laravel package discovery) that puts a UI lock over an authenticated session once a user has been idle for too long. It is a presentation/lock-state layer: the actual inactivity measurement generally comes from the rest of the tourze idle stack, so read the sibling packages before assuming this one times anything itself.

The 0.0.2 release notes contain no changelog body — only a link to the commit range. That tells you most of what you need to know for adoption: this is a pre-1.0 package with an unstable, undocumented API surface. Pin it exactly ("tourze/idle-lock-screen-bundle": "0.0.2") and read the source rather than the README.

Where to look first, in order:

1. composer.json in the package — its require tells you whether it drags in symfony/security-bundle, symfony/http-kernel constraints, and which idle-detection package it expects. Do this before composer require; a bad constraint here is the most likely reason adoption fails.
2. src/Resources/config/services.yaml — the real inventory of services, tags, and event subscribers.
3. src/DependencyInjection/Configuration.php — the full config tree under the bundle's root key. This is the authoritative docs for 0.0.x.
4. src/Resources/views/ and any controller under src/Controller/ — the lock screen itself, its route, and what it expects in the request.

Minimal Symfony wiring:

// config/bundles.php
Tourze\IdleLockScreenBundle\IdleLockScreenBundle::class => ['all' => true],

Then dump the routes (bin/console debug:router | grep -i lock) and the config reference (bin/console config:dump-reference <bundle_key>) to see what is actually exposed.

First use case: a logged-in user walks away from a kiosk/back-office screen; after the idle threshold the session is marked locked and the next request is redirected to a lock route that re-authenticates (password or PIN) to clear the lock, without destroying the rest of the session.

If you are working in Laravel rather than Symfony: treat this as a reference implementation, not a dependency. There is no Laravel service provider, the bundle is not auto-discovered, and the Symfony EventDispatcher/Security services it subscribes to do not exist in a Laravel request lifecycle. Port the pattern (session flag + middleware + lock view) instead of trying to boot the bundle.

Implementation Patterns

Server-side gate, client-side nudge. The durable pattern is a request middleware/subscriber that checks a last-activity timestamp on the session and marks the session locked when it exceeds the threshold. A small JS poller or visibilitychange listener can show the lock overlay proactively, but it must never be the only enforcement — otherwise a user with JS disabled or a stale tab is never locked. Treat any client-side idle timer in this bundle as a UX hint layered on top of the server check.

Lock, don't log out. The distinguishing behaviour versus a normal session timeout is that unlock restores the same session state. Keep the authenticated user in the session, set a separate locked_at/locked attribute, and have the guard deny-all-except-the-unlock-route while that attribute is present. Logout should be explicit, not a side effect of idling.

Route and firewall placement. Put the lock route outside the "authenticated and unlocked" access rule but behind IS_AUTHENTICATED_FULLY, and give the unlock form a CSRF token. If the lock route is caught by the same firewall rule as everything else you get a redirect loop; if it is fully anonymous you get an unlock endpoint that leaks whether a session exists.

Template override. Symfony bundle view overrides go in templates/bundles/<BundleName>/.... Overriding the lock screen markup is the lowest-risk customization and should be your first option before touching services.

Event-subscriber extension. For anything behavioural (audit logging, emitting a "session locked" metric, notifying the user) subscribe to the bundle's dispatched event or decorate its service rather than forking. Check debug:event-dispatcher for what it actually dispatches — on a 0.0.x package, event names can change between patch releases.

Laravel port, if that is the real target. Middleware that reads session('last_activity_at'), compares against config('auth.idle_lock.minutes'), sets session(['locked' => true]), and returns the lock view for any non-unlock route; an unlock POST that calls Auth::validate(...) and session()->regenerate(). Register the idle touch in the same middleware so there is exactly one writer of the timestamp.

Gotchas and Tips

No changelog for 0.0.2. Diff 0.0.1...0.0.2 on GitHub before upgrading. On a 0.0.x line, a patch bump is allowed to be breaking under most interpretations of semver, and with no notes you have no other signal.

Symfony-only assumptions. The bundle almost certainly type-hints Symfony\Component\HttpFoundation\* and Symfony\Component\Security\*. Under Laravel those classes may coexist in vendor/ but the wiring will not — expect to port, not install.

Idle time source ambiguity. Verify whether the threshold is measured server-side (request timestamps) or client-side (JS timer reported back). Server-side is trustworthy but means a backgrounded tab with no requests is never locked until the next request; client-side locks promptly but is bypassable. Many real deployments need both, and this bundle may only ship one half.

Multi-tab desync. Two tabs, one locks: the other renders stale content until its next request. Broadcast the lock (storage event / SSE / polling) if the screen is sensitive; otherwise accept that the next request is what actually protects you.

Session driver quirks. Lock state in the session is only as durable as the driver. Cookie-driver sessions can lose the flag as the cookie rotates; array driver in tests will not persist across requests at all.

Clock-dependent tests. Functional tests for an idle lock need a controllable clock (ClockMock for time()/sleep(), or an injected ClockInterface). Avoid sleep() in tests; assert with bin/console and a frozen clock, or the suite becomes slow and flaky.

Unlock should regenerate the session ID. If the package's unlock path does not, add it. Restoring a pre-idle session ID after a credential challenge defeats part of the point.

Debugging checklist: debug:container --tag=kernel.event_subscriber | grep -i idle to confirm the subscriber is registered, debug:router for the lock route name, debug:config <bundle_key> to confirm your config is actually merged (a typo'd root key is silently ignored), and the profiler's request/security panels to see why a request was or was not gated.