Laravel Legacy Bridge: Authentifizierte Sessions aus Altanwendungen in Laravel übertragen

Ein neues Paket von Chris Keller erlaubt es, Laravel schrittweise route für route zu migrieren, ohne dass Nutzer beim Wechsel zwischen alter und neuer App neu einloggen müssen. Es liest den Legacy-Session-Cookie, dekodiert die Payload aus der alten Datenbank und authentifiziert den passenden User in Laravel. Voraussetzung sind Laravel 13 und PHP 8.3.

Laravel Legacy Bridge ist ein Paket von Chris Keller (chr15k), das schrittweise Migrationen nach Laravel begleiten soll. Wenn ein Projekt route für route umgezogen wird, können Nutzer in der alten Anwendung eingeloggt sein, während Laravel-Routen sie als anonym behandeln. Das Paket schließt diese Lücke: Bei unauthentifizierten Anfragen liest es den Legacy-Session-Cookie, holt die passende Zeile aus der Legacy-Datenbank, dekodiert die Payload und ruft in Laravel loginUsingId() für den zugehörigen Nutzer auf. Sobald Laravel seine eigene Session geschrieben hat, greift das Middleware nicht mehr auf den Legacy-Store zurück.

Installiert wird es mit composer require chr15k/laravel-legacy-bridge und php artisan legacy-bridge:install. Der Installationsbefehl ist interaktiv, bietet Presets für gängige Legacy-Frameworks, fragt die Datenbank-Zugangsdaten ab und schreibt die nötigen .env-Einträge. Außerdem gibt es php artisan legacy-bridge:verify, optional mit einer konkreten Session-ID, um die Konfiguration anhand der echten Legacy-Datenbank zu testen – ohne dass jemand tatsächlich authentifiziert wird.

Konfigurierbar sind Payload-Format und Auflösung der Nutzer-ID. Unterstützt werden natives PHP-Session-Encoding, JSON, Laravels base64(serialize())-Format und verschlüsselte Payloads über LEGACY_BRIDGE_APP_KEY. Der Resolver läuft im Modus auto, über einen expliziten Key in Dot-Notation oder als eigene Klasse; eine Custom-Resolver eignet sich auch, um alte User-IDs auf neue zu mappen, wenn die Users-Tabelle neu angelegt wurde. Die README empfiehlt, mit auto zu starten und vor dem Livegang auf key oder custom umzustellen.

Statt eigener Logs werden typisierte Events gefeuert: LegacySessionBridged bei Erfolg, LegacySessionBridgeFailed bei bekannten Fehlern und LegacySessionBridgeError bei unerwarteten Exceptions. Fehler liefern eine BridgeFailureReason-Enum mit Fällen wie MissingCookie, AmbiguousCookie, SessionExpired, PayloadDecodeFailed und UserNotResolved, sowie ein BridgeContext-DTO mit Cookie-Name, Session-ID, Payload, User-ID und Request-Metadaten.

Derzeit werden nur Legacy-Datenbank-Sessions unterstützt, nicht File-, Redis- oder Memcached-Driver. Es gilt nur für Web-Requests, nicht für zustandslose API-Requests, und nur für den Default-Auth-Guard. Voraussetzung sind Laravel 13 und PHP 8.3 oder neuer. Sicherheitshinweise: Das Paket deserialisiert Payloads aus der Legacy-Sessions-Tabelle, daher sollte diese Datenbank als Vertrauensgrenze behandelt und besser nur lesend angebunden werden. Der Legacy-Cookie bleibt absichtlich unverschlüsselt, also müssen beide Apps HTTPS erzwingen. Die Standard-Invalidierungsstrategie after_write löscht die Legacy-Session, sobald Laravel eine eigene geschrieben hat; never sollte im Produktivbetrieb nicht verwendet werden. Optional lassen sich Werte wie Locale oder Cart-ID aus der Legacy-Payload in Laravel übernehmen.