---
title: "Laravel Legacy Bridge: перенесення автентифікованих сесій зі застарілих додатків у Laravel"
url: https://laravelukraine.com/blog/laravel-legacy-bridge-perenesennia-avtentifikovanix-sesii-zi-zastarilix-dodatkiv-u-laravel
author: "Олексій Бабінцев"
date: 2026-07-16
source: https://laravel-news.com/laravel-legacy-bridge-carry-authenticated-sessions-from-a-legacy-app-into-laravel?utm_medium=feed&utm_source=feedpress.me&utm_campaign=Feed%3A+laravelnews
---

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

Міграція застарілого додатка на Laravel по одному маршруту залишає вас із двома додатками та одним користувачем, який залогінений лише в одному з них. Користувач входить у старій частині на CodeIgniter чи кастомному PHP, переходить на маршрут, оброблений Laravel, і Laravel, не знаючи нічого про цю сесію, надсилає його до форми входу. Пакет Laravel Legacy Bridge від [Кріса Келлера](https://github.com/chr15k) зчитує 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 додає міст у шлях запиту:

```php
->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`:

```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`, що містить все, що міст визначив до зупинки:

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

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

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

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

## Команда verify

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

```bash
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](https://github.com/chr15k/laravel-legacy-bridge).