‏Legacy Bridge؛ کاربر لاگین‌کرده رو وارد لاراول می‌کنه

مهاجرت یه اپلیکیشن به لاراول به‌صورت روت‌به‌روت یه وضعیت عجیب می‌سازه: دو تا اپ داری و یه کاربر، که فقط تو یکیشون لاگینه. کاربر تو سمت قدیمی — CodeIgniter یا یه PHP دست‌ساز — وارد می‌شه، بعد به یه روت لاراولی می‌رسه و لاراول که چیزی از اون سشن نمی‌دونه، پرتش می‌کنه سراغ فرم لاگین. Laravel News معرفی کرده که پکیج Laravel Legacy Bridge از Chris Keller دقیقاً همین شکاف رو پر می‌کنه.

کافیه یه میدل‌ور رو تو مسیر درخواست ثبت کنی:

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

روی یه درخواست احراز هویت‌نشده، این میدل‌ور کوکی قدیمی (پیش‌فرض PHPSESSID) رو می‌خونه، رکوردش رو تو جدول سشن‌های دیتابیس قدیمی پیدا می‌کنه، پیلود رو رمزگشایی می‌کنه، شناسهٔ کاربر رو استخراج می‌کنه و loginUsingId() رو صدا می‌زنه. بعدش لاراول سشن خودش رو می‌نویسه و درخواست‌های بعدی اصلاً سراغ استور قدیمی نمی‌رن. سرویس‌پروایدر هم کوکی قدیمی رو از EncryptCookies مستثنا می‌کنه تا لازم نباشه لیستی نگه داری.

چون هر اپ قدیمی شناسهٔ کاربر رو زیر یه کلید متفاوت ذخیره کرده، نحوهٔ پیدا کردنش قابل تنظیمه. تو config/legacy-bridge.php یکی از سه درایور رو انتخاب می‌کنی:

'resolver' => ['driver' => 'auto'],
'resolver' => ['driver' => 'key', 'key' => 'user_id'],
'resolver' => ['driver' => 'custom', 'class' => \App\Bridge\LegacyUserResolver::class],

مستندات پیشنهاد می‌ده با auto شروع کنی ولی قبل از پروداکشن بری سراغ key یا custom. درایور سفارشی همون‌جاییه که اگه موقع مهاجرت جدول کاربرها رو دوباره سید کردی، شناسه‌های قدیمی رو به جدید نگاشت می‌کنی. فرمت پیلود هم تنظیم جداگانه‌ایه: auto، php_session، json، laravel یا encrypted — که حالت رمزنگاری‌شده کلید اپ قدیمی رو از LEGACY_BRIDGE_APP_KEY می‌خونه.

پکیج خودش هیچی تو لاگ نمی‌نویسه و به‌جاش رویداد می‌فرسته: LegacySessionBridged برای موفقیت، LegacySessionBridgeFailed برای خطاهای شناخته‌شده و LegacySessionBridgeError برای استثناهای غیرمنتظره. رویداد شکست یه enum به اسم BridgeFailureReason با هشت حالت داره — از MissingCookie و AmbiguousCookie تا SessionExpired، PayloadDecodeFailed و UserNotResolved — به‌علاوهٔ یه DTO که هر چیزی رو تا لحظهٔ توقف پیدا کرده نگه می‌داره.

نصبش با کامپوزر و یه دستور نصب تعاملیه که پریست فریم‌ورک‌های قدیمی رایج رو داره و خودش ورودی‌های .env رو می‌نویسه. کنارش دستور legacy-bridge:verify هست که پیکربندی رو مقابل دیتابیس واقعی تست می‌کنه: خوانا بودن کانفیگ، در دسترس بودن دیتابیس قدیمی، وجود جدول سشن‌ها، تنظیم بودن ریزالور و نبود تداخل تو نام کوکی‌ها. اگه یه شناسهٔ سشن واقعی بهش بدی، گزارش می‌ده که با اون سشن چه اتفاقی می‌افتاد — بدون اینکه کسی رو لاگین کنه یا چیزی رو تغییر بده.

محدودیت‌هاش صریح گفته شدن: این نسخه فقط سشن‌های دیتابیسی رو پشتیبانی می‌کنه (نه فایل، ردیس یا Memcached)، فقط درخواست‌های وب رو پل می‌زنه نه API بدون‌حالت، فقط روی گارد پیش‌فرض کار می‌کنه، و به لاراول ۱۳ و PHP ۸.۳ یا بالاتر نیاز داره.

بخش امنیت رو هم حتماً قبل از استقرار بخون. پل، پیلودهایی رو که مستقیم از جدول سشن قدیمی خونده deserialize می‌کنه، پس اون دیتابیس یه مرز اعتماده و نویسنده توصیه کرده تا جای ممکن با دسترسی فقط‌خواندنی وصلش کنی. کوکی قدیمی هم عمداً رمزنگاری‌نشده جابه‌جا می‌شه — دقیقاً مثل قبل — پس هر دو اپ به HTTPS نیاز دارن، و مستندات هشدار داده که استراتژی باطل کردن سشن قدیمی رو تو پروداکشن روی never نذاری.

نکات کلیدی:

• انتقال سشن احراز هویت‌شده از اپ قدیمی PHP به لاراول با یه میدل‌ور
• فقط روی درخواست‌های احراز هویت‌نشده اجرا می‌شه و بعدش کاری با استور قدیمی نداره
• سه درایور ریزالور (auto، key، custom) و پنج فرمت پیلود از جمله حالت رمزنگاری‌شده
• رویدادهای تایپ‌شده به‌جای لاگ‌نویسی، با enum هشت‌حالته برای دلیل شکست
• دستور verify برای تست پیکربندی مقابل دیتابیس واقعی، بدون تغییر چیزی
• محدود به سشن دیتابیسی، درخواست‌های وب و گارد پیش‌فرض؛ نیازمند لاراول ۱۳ و PHP ۸.۳