اگرچه زمان تخمینی آپگرید حدود ۱۰ تا ۳۰ دقیقه است، اما میزان پیچیدگی به طور مستقیم با حجم و پیچیدگی پروژه شما مرتبط است.

🎯 ویژگی‌های جدید لاراول ۱۳

🏷️ ۱. PHP Attributes Support (ویژگی‌های PHP)

لاراول ۱۳ از PHP 8 Attributes به عنوان جایگزینی برای property‌های کلاس برای پیکربندی اجزاء Laravel استفاده می‌کند. این یک تغییر غیرشکست‌پذیر است — پیکربندی مبتنی بر property‌های قدیمی همچنان کار می‌کند.

📚 Eloquent Models

اکنون می‌توانید از Attributes استفاده کنید تا نیازی به تعریف کردن $table، $hidden، $fillable و دیگر properties نباشد:

#[Table('users', key: 'user_id', keyType: 'string', incrementing: false)]
#[Hidden(['password'])]
#[Fillable(['name', 'email'])]
class User extends Model {}

Attributes دستیاب برای Models:

📋 Queue Jobs

اکنون می‌توانید پیکربندی Queue را مستقیماً روی کلاس Job تعریف کنید:

#[Connection('redis')]
#[Queue('podcasts')]
#[Tries(3)]
#[Timeout(120)]
class ProcessPodcast implements ShouldQueue {}

Attributes دستیاب برای Queue:

این Attributes همچنین برای Listeners، Notifications، Mailables و Broadcast Events قابل استفاده هستند.

🖥️ Console Commands

Commands می‌توانند signature و description خود را با Attributes به جای class properties تعریف کنند:

#[Signature('mail:send {user} {--queue}')]
#[Description('Send a marketing email to a user')]
class SendMailCommand extends Command {}

🎁 اجزای دیگر

Attributes همچنین برای موارد زیر قابل دسترس هستند:

• Form Requests: #[RedirectTo]، #[StopOnFirstFailure]
• API Resources: #[Collects]، #[PreserveKeys]
• Factories: #[UseModel]
• Test Seeders: #[Seed]، #[Seeder]

⏱️ ۲. Cache::touch() – تمدید TTL بدون دریافت مقدار

PR #55954 یک متد Cache::touch() اضافه می‌کند که TTL یک آیتم کش‌شده را بدون دریافت یا بازذخیره کردن مقدار تمدید می‌کند:

// Extend by seconds
Cache::touch('user_session:123', 3600);
 
// Extend with a DateTime
Cache::touch('analytics_data', now()->addHours(6));
 
// Extend indefinitely
Cache::touch('report_cache', null);

چرا این مهم است؟ قبلاً، تمدید TTL نیاز به get و سپس put داشت، که نیاز به انتقال مقدار کش‌شده بر روی سیم داشت. Cache::touch() این مرحله را رد می‌کند:

• Redis: یک فرمان EXPIRE استفاده می‌کند
• Memcached: TOUCH استفاده می‌کند
• Database: یک UPDATE صادر می‌کند

متد true در صورت موفقیت و false در صورتی که کلید موجود نباشد برمی‌گرداند.

🐍 ۳. نسخه PHP مورد نیاز

لاراول ۱۳ نیاز به PHP 8.3 به عنوان حداقل نسخه دارد. این نمایندگی یک افزایش از نسخه ۱۲ (PHP 8.2) است.

📦 بروزرسانی وابستگی‌ها

اولین و مهم‌ترین گام، بروزرسانی فایل composer.json است:

{
  "require": {
    "php": "^8.3",
    "laravel/framework": "^13.0",
    "laravel/tinker": "^3.0",
    "laravel/sanctum": "^4.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^12.0",
    "laravel/pint": "^1.17",
    "laravel/sail": "^1.30"
  }
}

سپس این دستورات را اجرا کنید:

rm -rf vendor composer.lock
composer install
composer dump-autoload

🛡️ تغییرات Middleware و CSRF

تغییر نام VerifyCsrfToken

یکی از مهم‌ترین تغییرات در لاراول ۱۳:

مراحل انتقال:

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;

->withoutMiddleware([PreventRequestForgery::class])

⚙️ تنظیمات کَش و Serialization

گزینه جدیدی به نام serializable_classes به کانفیگ کش اضافه شده که به طور پیش‌فرض false است. این کار جلوی حملات deserialization gadget chain را می‌گیره.

// config/cache.php
return [
    'serializable_classes' => [
        App\Models\User::class,
        App\Data\CachedDashboardStats::class,
    ],
];

🗄️ تغییرات Eloquent و دیتابیس

متد upsert() – اعتبارسنجی اجباری

حالا متد upsert حتماً نیاز به یک مقدار غیرتهی برای uniqueBy دارد.

User::upsert(
    [
        ['email' => 'john@example.com', 'name' => 'John'],
        ['email' => 'jane@example.com', 'name' => 'Jane'],
    ],
    'email',  // uniqueBy - اجباری
    ['name', 'updated_at']  // updateFields
);

🔄 Queue و Event‌های جدید

JobAttempted Event

خاصیت exceptionOccurred حذف و با $event->exception جایگزین شد.

use Illuminate\Queue\Events\JobAttempted;

Queue::listen(JobAttempted::class, function (JobAttempted $event) {
    if ($event->exception !== null) {
        Log::error('Job failed', ['exception' => $event->exception]);
    }
});

QueueBusy Event

خاصیت $connection به $connectionName تغییر نام داد.

use Illuminate\Queue\Events\QueueBusy;

class ListenerQueueBusy
{
    public function handle(QueueBusy $event)
    {
        Log::info("Queue busy: {$event->connectionName}");
    }
}

🌐 مسیریابی و Routing

تغییر الویت Route

الویت تطابق مسیرها عوض شده: مسیرهایی که دامنه (domain) مشخص دارند، اولویت بیشتری نسبت به مسیرهای بدون دامنه دارند.

// الویت 1 - Domain مشخص
Route::domain('api.example.com')->group(function () {
    Route::get('/users', 'UserController@index');
});

// الویت 2 - بدون Domain
Route::get('/users', 'UserController@index');

🧪 تغییرات Testing

String Factories – Reset بین تست‌ها

کارخانه‌های UUID و string دیگر بین تست‌ها ریست می‌شوند. اگر در تست‌های مختلف به persist شدن این فیکسچرها تکیه کرده بودید، باید در هر تست یا در متد setUp دوباره مقداردهی کنید.

public function setUp(): void
{
    parent::setUp();
    
    Str::createUuidsUsing(function () {
        return Str::uuid();
    });
}

Js::from() – Unicode Unescaping

حالا به طور پیش‌فرض از JSON_UNESCAPED_UNICODE استفاده می‌کند.

✅ بهترین روش‌های آپگرید

📋 چک‌لیست پیش آپگرید

1. Backup دیتابیس و فایل‌های پروژه

   git commit -am "Pre-upgrade backup"
   mysqldump -u user -p database > backup.sql

   کپی

2. بررسی نسخه PHP (باید 8.3+ باشد)

   php -v

   کپی

3. اجرای تست‌های موجود

   php artisan test --stop-on-failure

   کپی

🐛 Troubleshooting

🎯 نتیجه‌گیری

لاراول ۱۳ آپگرید سرمایه‌گذاری ارزشمندی برای امنیت و عملکرد است. ویژگی‌های جدید مثل PHP Attributes و Cache::touch() توسعه را آسان‌تر می‌کنند.