Auth Log Bundle Laravel Package

Getting Started

spiriitlabs/auth-log-bundle (v4.0.2) persists authentication attempts — success and failure — as Doctrine entities, with optional geolocation of the source IP. Despite the "Laravel developer" framing, it is a Symfony bundle; treat it as a PHP package you either use inside a Symfony service or port the listener/manager pattern from into a Laravel app.

Minimal path:

1. composer require spiriitlabs/auth-log-bundle:^4.0 (plus geoip2/geoip2 if you want local lookups — see below).
2. Register the bundle (config/bundles.php) and import its routing/config if you want the built-in endpoints.
3. Generate and run the Doctrine migration for the auth log table; confirm the entity is mapped.
4. Configure config/packages/auth_log.yaml: enable the listener, pick a location provider, and (new in 4.0.2) set the HTTP provider timeout.
5. First use case: let the security listener record LoginSuccessEvent / LoginFailureEvent automatically, then query the repository for failed attempts per IP/user in the last N minutes.

In Laravel, the equivalent first step is to register an event listener on Illuminate\Auth\Events\Login / Failed that calls the bundle's manager service (or your own port of it).

Implementation Patterns

Automatic logging via the security listener. The default integration hooks Symfony's security events. Zero application code, but only covers the standard authenticator flow — custom token handling, API key guards, or passwordless flows won't fire it.

Manual logging through the manager service. For non-standard flows (Laravel guards, custom API auth, SSO callbacks) inject the auth log manager and call it explicitly with the user identifier, firewall/guard name, and request. This is the pattern to use when porting to Laravel: one listener per auth event, manager as a singleton, repository for reads.

Provider strategy: geoip2 in production, HTTP API in dev. v4.0.2's docs change makes this explicit — geoip2 (local MaxMind .mmdb) is the recommended production choice; the HTTP-based provider is convenient but network-bound. Configure the provider per environment.

Bounded HTTP lookups. The 4.0.2 fix adds a timeout on the API-based location provider. Set it explicitly (low, e.g. 1–2s) so a slow geo API never delays the login response or the log write. Pair it with a graceful fallback: log the attempt with a null location rather than dropping the record.

Async location enrichment. 4.0.2 adds symfony/messenger and symfony/http-client as suggested deps. The intended pattern is: write the auth log synchronously (fast, reliable), dispatch location resolution to a message handler, update the record asynchronously. This decouples login latency from third-party availability — strongly recommended if you stay on an HTTP provider.

Read-side patterns. Build dashboards/queries on: failures per IP in a window (brute force), distinct countries per user (impossible travel), success-after-N-failures sequences. Add a scheduled cleanup/retention job — the table grows on every login attempt.

Gotchas and Tips

• The timeout fix is a mitigation, not a solution. 4.0.2 prevents a hanging request, but every login still pays the lookup latency on the HTTP provider. Move to geoip2 for production, or go async via Messenger.
• geoip2 requires real setup: the composer package, a licensed .mmdb file on disk, a configurable path, and a refresh cadence (MaxMind updates weekly). It fails closed and silently if the DB is missing — verify it returns a country in staging before trusting the data.
• Messenger and HTTP client are suggest, not require. Composer won't install them. Add them explicitly if you follow the async pattern, and make sure a transport + worker is actually running, otherwise location data never lands.
• Logging the wrong IP behind a proxy/load balancer. Configure trusted proxies (or the Laravel equivalent TrustProxies middleware) or every record will show your ingress IP and geolocation becomes useless.
• GDPR/retention. You are storing IPs and geodata tied to user identifiers. Decide anonymization (hash/truncate IP after N days), retention window, and whether success events need logging at all — failure-only is often enough and far lower risk.
• Schema ownership. The bundle ships an entity; if you extend it or add columns/indexes (you will want an index on (identifier, created_at) and on ip), keep your migration separate so bundle upgrades don't fight you.
• Laravel portability caveat. There is no Laravel service provider. Budget for a thin bridge: bind the manager, map the entity to Eloquent or keep Doctrine alongside, and re-implement the event wiring. If the effort exceeds a day, a Laravel-native auth-log package is the more honest choice.
• Debugging: log provider failures at warning (not error) with the fallback taken, and check the profiler/log channel for silent geolocation failures — the 4.0.2 timeout surfaces as an exception the bundle swallows, so a "missing country" is your only symptom.
• Extension points: the location provider interface (swap in your own, e.g. a cached/queued decorator) and the manager service (decorate it to add tenant/context fields) are the two seams worth using before forking anything.