‏لاراول 13.12.0: متادیتا روی تسک‌های زمان‌بندی و کنترل کشف Listener

لاراول 13.12.0 یه سری قابلیت کاربردی برای توسعه‌دهنده‌ها آورده که مهم‌ترینشون مربوط به scheduler و سیستم رویدادهاست.

متادیتا روی تسک‌های زمان‌بندی با withAttributes()

تا حالا اگه می‌خواستی اطلاعات اضافه‌ای (مثل تگ یا نام) رو به یه تسک زمان‌بندی‌شده وصل کنی، مجبور بودی از description یا command string استفاده کنی. حالا با متد withAttributes() می‌تونی هر key-value دلخواهی رو مستقیماً روی رویداد ذخیره کنی و داخل callback‌های lifecycle مثل after() بهش دسترسی داشته باشی. این برای مانیتورینگ و ثبت متریک‌ها خیلی مفیده:

Schedule::after(function (Event $event) {
    $tag = $event->attributes['tag'] ?? null;
    if ($tag) {
        Metrics::increment(
            $event->exitCode === 0 ? 'scheduled.succeeded' : 'scheduled.failed',
            tags: ['command' => $tag]
        );
    }
})->group(function (Schedule $schedule) {
    $schedule->command('audio:import-podcasts --only-premium')
        ->withoutOverlapping()
        ->withAttributes(['tag' => 'import-premium-podcasts']);
});

کنترل کشف Listener با ShouldBeDiscovered

در لاراول، Listenerهایی که داخل پوشه‌ی مخصوص قرار می‌گیرن به‌صورت خودکار کشف و ثبت می‌شن. اما گاهی می‌خوای یه Listener فقط در محیط‌های خاص (مثلاً production) فعال باشه. با اینترفیس جدید ShouldBeDiscovered می‌تونی متد استاتیک shouldBeDiscovered() رو پیاده‌سازی کنی و بگی چه وقت این Listener باید ثبت بشه. اگه false برگردونه، اصلاً به صف اضافه نمی‌شه — که خیلی بهتر از اینه که بره توی صف و بعد داخل handle() هیچ‌کاری نکنه.

class NotifyExternalCrm implements ShouldBeDiscovered, ShouldQueue
{
    public static function shouldBeDiscovered(): bool
    {
        return app()->environment('production');
    }

    public function handle(CustomerRegistered $event): void
    {
        Http::post(config('services.crm.webhook'), [
            'email' => $event->customer->email,
        ]);
    }
}

خاموش کردن ری‌استارت worker هنگام قطع اتصال

وقتی Queue Worker اتصال پایگاه داده رو از دست می‌ده، به‌صورت پیش‌فرض ری‌استارت می‌شه. اگه چند اتصال (مثل replica) داری و یکیشون موقتاً قطع بشه، این رفتار می‌تونه باعث boot-loop بشه. حالا با Worker::$stopOnLostConnection = false می‌تونی این رفتار رو غیرفعال کنی تا worker فقط خطا رو لاگ کنه و به کارش ادامه بده.

سایر بهبودها

پشتیبانی از فرمت URI با پیشوند file: برای اتصال‌های SQLite اضافه شده که می‌تونی گزینه‌هایی مثل cache=shared رو مستقیم توی connection string تعریف کنی. متدهای Str::studly() و Str::pascal() هم یه پارامتر normalize گرفتن که وقتی true باشه، کلمات تماماً بزرگ (مثل ALL_CAPS) رو قبل از تبدیل کوچک می‌کنه تا خروجی درستی بگیری. دستورات Artisan مثل cache:clear و key:generate هم حالا می‌تونن با Artisan::prohibit() در محیط production قفل بشن.

یه باگ مهم هم رفع شده: از نسخه‌ی 13.10.0، اگه پارامتر callback توی scheduler اسمش $event نبود (مثلاً $scheduledEvent)، یه خطای BindingResolutionException می‌داد. حالا پارامتر بر اساس نوع (type) حل می‌شه، نه اسم — درست مثل بقیه‌ی Container لاراول.

نکات کلیدی:

• متد withAttributes() برای افزودن متادیتای دلخواه به تسک‌های scheduler
• اینترفیس ShouldBeDiscovered برای کنترل شرطی کشف Listener
• Worker::$stopOnLostConnection = false برای جلوگیری از boot-loop در قطعی موقت اتصال
• پشتیبانی از SQLite URI با پیشوند file:
• پارامتر normalize در Str::studly() و Str::pascal()
• رفع باگ تزریق وابستگی در callback‌های scheduler بر اساس type