Queue::forward(): перенаправляйте Laravel queues в одному місці

Назви черг часто «зашиваються» в коді: від параметрів onQueue('reports') у класах Job до налаштувань onConnection('redis') під час виклику. Коли черга звітів починає перевантажувати систему, і ви хочете винести її на окремий Redis-інстанс або перейти на FIFO-черги в хмарі, доводиться вносити правки всюди, включно зі сторонніми пакетами, на які ви не маєте впливу.

Laravel 13.26 розв'язує цю проблему за допомогою методу Queue::forward(), запропонованого @jackbayliss у #61188. Тепер можна в одному місці вказати, що завдання для певної черги мають потрапляти на іншу чергу чи з'єднання. Весь інший код продовжує звертатися до reports, а forward визначає актуальний шлях.

# API

Метод дозволяє гнучко налаштовувати переспрямування:

use Illuminate\Support\Facades\Queue;
 
// Змінити назву черги та перенести її на інше з'єднання
Queue::forward('reports', 'reports.fifo', 'cloud');
 
// Змінити лише з'єднання, залишивши назву черги
Queue::forward('payments', connection: 'cloud');
 
// Перейменувати чергу в межах одного з'єднання
Queue::forward('updates', 'notifications');
 
// Перенаправити кілька черг одночасно
Queue::forward([
    'reports' => 'reports.fifo',
    'emails' => 'emails.fifo',
], connection: 'cloud');

Назви черг можуть бути рядками або Backed Enums. Виклики варто розміщувати в методі boot() сервіс-провайдера. Нова функція інтегрована в ядро через той самий хук getConnection(), що й Queue::route(), тому вона працює з усіма драйверами без додаткових змін у їхньому коді.

Важливий нюанс: якщо у forward вказано конкретне з'єднання, перейменування спрацює лише для завдань, що прямують саме туди. Наприклад, Queue::forward('reports', 'reports.fifo', 'cloud') перенаправить загальні виклики reports у хмару, але завдання, явно відправлені на reports через з'єднання redis, залишаться без змін. Це точкове зіставлення, а не глобальна автозаміна.

# Маршрутизація залежно від середовища

Завдяки реєстрації у провайдері, маршрутизацію легко зробити умовною, що значно зручніше за статичні конфіг-файли. Класичний приклад — використання Redis локально та керованого сервісу в продакшені:

namespace App\Providers;
 
use Illuminate\Support\Facades\Queue;
use Illuminate\Support\ServiceProvider;
 
class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->isProduction()) {
            Queue::forward([
                'reports' => 'reports.fifo',
                'emails' => 'emails.fifo',
            ], connection: 'cloud');
        }
    }
}

Тепер у локальному середовищі dispatch(new GenerateReport) піде в Redis-чергу reports, а в продакшені той самий код автоматично спрямує завдання в reports.fifo на хмарному з'єднанні. Більше жодних перевірок середовища всередині Job-класів або складних маніпуляцій у config/queue.php.

Це також спрощує оперативне керування навантаженням:

// Якщо черга обробки відео перевантажує основний Redis:
Queue::forward('encoding', connection: 'redis-heavy');
 
// Тестування нового з'єднання на одній другорядній черзі:
Queue::forward('notifications', connection: 'sqs-experiment');

Оскільки переспрямування додається одним рядком, відкат змін відбувається так само просто — видаленням цього рядка. Це робить поступову міграцію черг максимально безпечною.

# Чого Forwarding не робить

Переспрямування працює лише в момент відправки завдання (dispatch). Завдання, які вже знаходяться в черзі, залишаться на старому місці. Тому під час міграції важливо залишити воркери на старій черзі, поки вони не вичерпають її залишок. Одночасна робота воркерів зі старими та новими назвами протягом тривалого часу може призвести до race conditions, тому стару чергу слід вважати застарілою і вимикати її воркери одразу після очищення.

Варто зауважити: `forward` лише змінює шлях, він не зупиняє і не обмежує потік завдань. Для призупинення обробки використовуйте Queue Pause API з Laravel 13.25. Якщо ж проблема в занадто великій кількості подій, зверніть увагу на Debounced Listeners, які з’явилися в цьому ж релізі.

# Що почитати

• Огляд релізу Laravel 13.26 зі списком усіх оновлень
• Основи Laravel Jobs та черг: з'єднання, пріоритети та робота з кількома чергами
• Пауза черг у Laravel 13.25 — інструмент для керування споживанням завдань