Laravel 13 : Queue::route() pour centraliser toute votre topologie de queues

Si vous avez déjà travaillé sur une application Laravel en production pendant quelques mois, vous connaissez probablement ce moment où la gestion des queues devient un vrai casse-tête. On commence simplement : une queue par défaut, tous les jobs s'y retrouvent, tout va bien. Puis vient le jour où un client se plaint de la lenteur des emails, alors on crée une queue dédiée. Ensuite les webhooks Stripe s'accumulent, donc une queue billing fait son apparition. Bientôt, des traitements IA gourmands en ressources nécessitent une connexion Redis séparée.

Six mois plus tard, la configuration de vos queues est éparpillée partout : dans les propriétés $queue de certaines classes de jobs, dans des chaînes ->onQueue() disséminées dans vos contrôleurs, et dans des commandes planifiées. Changer un nom de queue revient à faire un grep sur toute la base de code. Laravel 13 apporte une réponse claire à ce problème avec Queue::route().

Le problème : une configuration éclatée en plusieurs endroits

Voici un exemple typique de ce que l'on retrouve dans une application Laravel ayant grossi organiquement :

// Dans un Job
class ProcessInvoice implements ShouldQueue
{
    public $queue = 'billing';
}

// Dans un contrôleur
ProcessInvoice::dispatch()->onQueue('billing-urgent');

// Dans une commande Artisan
App\Jobs\ProcessInvoice::dispatch()->onQueue('billing');

Le même job est potentiellement acheminé vers des queues différentes selon l'endroit depuis lequel il est dispatché. Résultat : aucune cohérence, aucune lisibilité, et une maintenance difficile pour toute l'équipe.

La solution Laravel 13 : Queue::route()

Laravel 13 introduit Queue::route(), qui suit la même philosophie que RateLimiter::for() pour les rate limits ou Route::model() pour le model binding : la configuration d'infrastructure appartient à un seul endroit.

La méthode se déclare typiquement dans un Service Provider, par exemple dans AppServiceProvider :

use Illuminate\Support\Facades\Queue;
use App\Jobs\ProcessInvoice;
use App\Jobs\SendEmail;
use App\Jobs\GenerateAIReport;

public function boot(): void
{
    Queue::route([
        ProcessInvoice::class  => 'billing',
        SendEmail::class       => 'emails',
        GenerateAIReport::class => 'heavy:redis-high-memory',
    ]);
}

Désormais, peu importe où le job est dispatché dans l'application, il sera automatiquement orienté vers la bonne queue. Plus besoin de spécifier ->onQueue() à chaque appel ni de définir $queue dans chaque classe.

Routing basé sur des interfaces

L'un des aspects les plus puissants de Queue::route() est la possibilité de router par interface plutôt que par classe concrète. Cela permet de définir des conventions claires au niveau architectural :

use App\Contracts\Jobs\BillingJob;
use App\Contracts\Jobs\HeavyProcessingJob;

Queue::route([
    BillingJob::class        => 'billing',
    HeavyProcessingJob::class => 'heavy:redis-high-memory',
]);

Tout nouveau job implémentant BillingJob sera automatiquement acheminé vers la queue billing. Plus besoin d'y penser à chaque création de job : la convention est définie une fois, respectée partout.

class RefundPayment implements ShouldQueue, BillingJob
{
    // Aucune configuration de queue nécessaire
    public function handle(): void
    {
        // ...
    }
}

Précédence des règles de routing

Il est important de comprendre l'ordre de priorité appliqué par Laravel lorsque plusieurs règles de routing peuvent s'appliquer :

1. La valeur passée via ->onQueue() au moment du dispatch (priorité maximale)
2. La règle définie par classe concrète dans Queue::route()
3. La règle définie par interface dans Queue::route()
4. La propriété $queue définie dans la classe du job
5. La queue par défaut de la configuration (config/queue.php)

Cette hiérarchie permet de conserver une flexibilité ponctuelle tout en maintenant une configuration centralisée comme source de vérité.

Mise en pratique : organiser son AppServiceProvider

Pour une application avec plusieurs domaines fonctionnels, voici une organisation recommandée :

public function boot(): void
{
    Queue::route([
        // Jobs de facturation
        ProcessInvoice::class    => 'billing',
        RefundPayment::class     => 'billing',
        SendReceipt::class       => 'billing',

        // Notifications
        SendEmail::class         => 'notifications',
        SendSmsAlert::class      => 'notifications',

        // Traitements lourds sur connexion dédiée
        GenerateAIReport::class  => 'heavy:redis-high-memory',
        ProcessVideoUpload::class => 'heavy:redis-high-memory',
    ]);
}

Le format queue:connection permet de spécifier simultanément la queue et la connexion Redis à utiliser, ce qui était auparavant nécessitait deux appels distincts (->onQueue() et ->onConnection()).

Ce que cela change concrètement pour votre équipe

Avant Queue::route() : un développeur qui rejoint l'équipe doit fouiller les classes de jobs, les contrôleurs et les commandes Artisan pour comprendre où part chaque job.

Après Queue::route() : une seule lecture du Service Provider suffit pour avoir une vision complète de la topologie des queues.

Les bénéfices concrets sont nombreux :

• Onboarding facilité : la topologie des queues est documentée implicitement dans le code
• Refactoring simplifié : renommer une queue se fait en un seul endroit
• Cohérence garantie : impossible d'avoir deux comportements différents pour un même job selon le contexte de dispatch
• Séparation des responsabilités : la logique métier du job est séparée de la configuration d'infrastructure

Conclusion

Queue::route() est une fonctionnalité qui peut sembler anodine à première vue, mais qui répond à un problème très réel rencontré dans de nombreuses applications Laravel en croissance. En centralisant la configuration du routing des queues dans un Service Provider, Laravel 13 encourage une meilleure organisation du code et facilite la vie des équipes techniques.

Cette approche s'inscrit dans la continuité de la philosophie Laravel : offrir des abstractions élégantes qui permettent de garder le code lisible et maintenable, même quand la complexité métier augmente.

Si vous gérez une application avec plusieurs queues et des workers dédiés, la migration vers Queue::route() est une refactorisation simple et à fort retour sur investissement.

Cet article s'inspire de l'article original publié par Hafiz sur dev.to.