Laravel Legacy Bridge: перенесення автентифікованих сесій із застарілих застосунків у Laravel

Поступове перенесення застосунку на Laravel по одному роуту за раз часто створює незручності для користувачів: вони авторизуються в старій частині (на CodeIgniter або власному PHP), але при переході на сторінку під керуванням Laravel система їх не впізнає і знову просить увійти. Пакет Laravel Legacy Bridge від Кріса Келлера розв'язує цю проблему: він зчитує legacy-куки сесії, декодує дані зі старої бази та автоматично авторизує відповідного користувача в Laravel.

Основні можливості пакета:

• Middleware-міст: працює лише для неавторизованих запитів і перестає звертатися до старої бази, щойно Laravel створює власну сесію.
• Декодування payload: підтримує нативне кодування PHP-сесій, JSON, формат Laravel base64(serialize()) та зашифровані дані.
• Драйвери Resolver: дозволяють знайти ID користувача в payload за допомогою автовизначення, прямого ключа в dot-notation або власного класу.
• Типізовані події: сповіщення про успішний перехід, відомі помилки або винятки без зайвого засмічення логів.
• Інвалідація legacy-сесії: можливість налаштувати одноразове використання старої сесії для міграції.
• Інтерактивні команди: швидке встановлення з пресетами для фреймворків та команда verify для тестування з’єднання перед запуском у продакшн.
• Перенесення контексту: опціональне збереження значень на кшталт локалі чи ID кошика зі старого payload.

# Як працює міст

Для активації достатньо додати middleware у конвеєр запитів:

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Chr15k\LegacyBridge\Http\Middleware\LegacySessionBridge::class,
    ]);
})

Отримавши неавторизований запит, пакет зчитує застарілу cookie (за замовчуванням PHPSESSID), знаходить відповідний рядок у таблиці сесій старої бази, декодує payload, визначає ID користувача та викликає loginUsingId(). Після цього Laravel створює власну сесію, а наступні запити вже не звертаються до старої бази. Пакет також автоматично виключає legacy-куку з обробки middleware EncryptCookies.

# Резолвери та формати даних

Оскільки кожен застосунок зберігає ID користувача під різними ключами, логіка пошуку гнучко налаштовується у файлі config/legacy-bridge.php:

// Auto: спроба знайти відомі патерни (за замовчуванням)
'resolver' => ['driver' => 'auto'],
 
// Key: прямий шлях через крапку
'resolver' => ['driver' => 'key', 'key' => 'user_id'],
 
// Custom: ваша власна реалізація
'resolver' => ['driver' => 'custom', 'class' => \App\Bridge\LegacyUserResolver::class],

Розробник рекомендує починати з auto, але переходити на key або custom перед релізом. Власний резолвер корисний, якщо при міграції бази даних ID користувачів змінилися. Формат payload налаштовується окремо (php_session, json, laravel або encrypted).

# Події

Пакет нічого не пише в логи самостійно. Замість цього він генерує події: LegacySessionBridged при успіху, LegacySessionBridgeFailed у разі відомих проблем та LegacySessionBridgeError для непередбачуваних помилок.

Помилки містять Enum BridgeFailureReason з вісьмома варіантами, серед яких MissingCookie, SessionExpired та UserNotResolved. Об'єкт BridgeContext передає в подію всі дані, які міст встиг зібрати до моменту помилки:

$event->context->cookieName
$event->context->sessionId      // ID сесії
$event->context->payload        // декодований payload
$event->context->userId         // знайдений ID користувача
$event->context->requestContext // контекст запиту: IP, шлях, метод, UA

# Встановлення

composer require chr15k/laravel-legacy-bridge
php artisan legacy-bridge:install

Команда встановлення в інтерактивному режимі допоможе вибрати пресет для фреймворка, налаштувати підключення до бази та запише необхідні змінні в .env.

# Перевірка конфігурації

Оскільки помилки в конфігурації важко відстежити звичайними тестами, пакет має спеціальну команду для діагностики:

php artisan legacy-bridge:verify
php artisan legacy-bridge:verify --session-id=a_real_session_id

Без параметрів вона перевіряє доступність бази та наявність таблиць. Якщо передати реальний ID сесії, команда покаже повний шлях обробки: чи розпізнано формат, чи знайдено ID користувача та чи існує такий користувач у новій системі. При цьому ніякі дані не змінюються, а авторизація не відбувається.

# Обмеження та безпека

Перша версія підтримує лише сесії в базі даних (не Redis чи файли), працює тільки з вебзапитами та стандартним guard авторизації. Необхідні Laravel 13 та PHP 8.3 або новіше.

З точки зору безпеки важливо пам'ятати: оскільки міст десеріалізує дані безпосередньо зі старої бази, вона стає критичною зоною довіри. Автор рекомендує використовувати read-only доступ до legacy-бази. Оскільки стара кука зазвичай передається нешифрованою, обидва застосунки повинні працювати через HTTPS. Стратегія after_write видаляє стару сесію одразу після створення сесії Laravel, що є рекомендованим налаштуванням для продакшну.

Вихідний код та повна документація доступні на GitHub.