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

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

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

Пакет охоплює наступний функціонал:

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

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

Реєстрація одного middleware додає міст у шлях запиту:

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

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

Резолвери та формати payload

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

// Auto: пробує відомі шаблони (за замовчуванням)
'resolver' => ['driver' => 'auto'],

// Key: явний шлях у dot-нотації
'resolver' => ['driver' => 'key', 'key' => 'user_id'],

// Custom: власна реалізація
'resolver' => ['driver' => 'custom', 'class' => \App\Bridge\LegacyUserResolver::class],

README рекомендує починати з auto і переходити на key або custom перед продакшеном. Кастомний resolver також є місцем, де можна змапити старі ID користувачів на нові, якщо під час міграції таблиця users була пересіяна. Формат payload - це окреме налаштування (auto, php_session, json, laravel або encrypted), а зашифрований формат зчитує ключ застарілого додатка з LEGACY_BRIDGE_APP_KEY.

Події

Міст нічого не записує у ваші лог-файли. Він диспатчить LegacySessionBridged при успіху, LegacySessionBridgeFailed для відомих помилок і LegacySessionBridgeError для неочікуваних винятків, залишаючи звітування вашим слухачам.

Помилки містять enum BridgeFailureReason з вісьмома варіантами, серед яких MissingCookie, AmbiguousCookie, SessionExpired, PayloadDecodeFailed та UserNotResolved. Деякі вказують на неправильну конфігурацію, інші є звичайними, як-от сесія з вичерпаним часом. Подія помилки також несе DTO BridgeContext, що містить все, що міст визначив до зупинки:

$event->context->cookieName
$event->context->sessionId      // визначений ID сесії (якщо досягнуто)
$event->context->payload        // декодований payload (якщо досягнуто)
$event->context->userId         // визначений ID користувача (якщо досягнуто)
$event->context->requestContext // ['ip', 'path', 'method', 'user_agent']

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

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

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

Команда verify

Неправильно налаштований міст падає на реальних cookies проти реальної legacy-бази даних, що не є тим, що тестує ваш тестовий набір. Пакет постачається з командою, яка перевіряє конфігурацію проти цієї бази даних:

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

Запустіть її без параметрів, і вона перевірить, що конфіг читається, legacy-база даних доступна, таблиця сесій існує та має рядки, resolver налаштований, і немає конфліктів імен cookies. Передайте реальний ID сесії, і вона повідомить, що міст зробив би з цією сесією: виявлений формат, знайдені ключі payload, визначений ID користувача, підтверджено існування користувача. Вона нікого не автентифікує і нічого не модифікує.

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

Перший реліз підтримує лише database-сесії, не file, Redis чи Memcached драйвери. Він працює з веб-запитами, не зі stateless API-запитами, і лише з дефолтним auth guard. Потребує Laravel 13 та PHP 8.3 або новіше.

Прочитайте розділ безпеки README перед деплоєм. Міст десеріалізує payload, зчитані безпосередньо з таблиці legacy-сесій, що робить цю базу даних межею довіри; автор рекомендує використовувати облікові дані лише для читання, де це можливо. Legacy-cookie передається незашифрованим за дизайном, так само, як це було в старому додатку, тому обидва додатки потребують HTTPS. Дефолтна стратегія інвалідації after_write видаляє legacy-сесію після того, як Laravel записує власну, і документація радить не встановлювати її на never у продакшені.

Вихідний код та повний посібник користувача, що охоплює пресети фреймворків, стратегії інвалідації та усунення несправностей, доступні на GitHub.