Enregistrement et portée des middlewares d'un package

Lorsque vous ajoutez des fonctionnalités HTTP à un package, distinguez le fait de rendre un middleware disponible du fait de l’appliquer aux requêtes de l’application qui l’utilise. Si la simple installation du package ne modifie pas le comportement de toutes les routes, il devient plus facile de maîtriser l’impact de son adoption et sa compatibilité future. Cette page suppose que vous connaissez les bases du développement de packages et s’appuie sur la documentation officielle de Laravel 13.x ainsi que sur l’implémentation du Framework v13.36.0. Pour l’écriture classique d’un middleware, consultez Middleware.

Distinguer enregistrement, application et exécution

Router::aliasMiddleware() enregistre dans un tableau du Router l’alias comme clé et le nom de classe comme valeur. Il ne crée pas d’instance du middleware et ne l’applique à aucune route.

Opération	Rôle	Ce qui n’est pas fait à elle seule
`aliasMiddleware()`	Enregistre la correspondance entre un nom et une classe	L’application aux requêtes
`middleware()` sur une route	L’assigne à la route ciblée	L’implémentation propre de la classe de middleware
`middlewareGroup()`	Définit le contenu d’un groupe nommé	L’ajout aux middlewares globaux
Ajout à la pile globale du HTTP Kernel	Cible toutes les requêtes	La prise en charge des exclusions par route

Le nom d’alias fait partie de l’API publique. Évitez les noms intégrés comme auth ou throttle, ainsi que les noms génériques susceptibles d’entrer en conflit avec d’autres packages, et ajoutez un préfixe propre au package. Si vous enregistrez de nouveau la même clé, aliasMiddleware() écrase la correspondance précédente.

Exposer l’alias depuis le service provider

Dans l’exemple suivant, nous créons un middleware qui ajoute un en-tête d’identification fixe à la réponse. Il ne s’agit pas d’un exemple d’authentification, d’autorisation ou de contrôle d’accès. On suppose que le PSR-4 de Composer fait correspondre Acme\Courier\ à src/ et que le service provider est enregistré par découverte automatique ou manuellement.

src/Http/Middleware/AddCourierHeader.php

<?php

namespace Acme\Courier\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class AddCourierHeader
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        $response->headers->set('X-Acme-Courier', 'enabled');

        return $response;
    }
}

Utilisez le Router dans boot(). Les arguments de boot() sont injectés par le conteneur de services : il n’est donc pas nécessaire de modifier automatiquement le bootstrap/app.php de l’utilisateur pour enregistrer le middleware.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Acme\Courier\Http\Middleware\AddCourierHeader;
use Illuminate\Routing\Router;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(Router $router): void
    {
        $router->aliasMiddleware('acme-courier.header', AddCourierHeader::class);
    }
}

Démarrez ce service provider comme un service provider classique. Si vous déplacez l’enregistrement de l’alias dans un service provider différé qui ne s’exécute que lorsqu’un autre service est résolu, rien ne garantit plus que l’alias sera enregistré au moment où la route en a besoin.

L’utilisateur l’applique route par route

Dans le fichier routes/web.php de l’application, assignez-le uniquement aux routes qui en ont besoin.

routes/web.php

<?php

use Illuminate\Support\Facades\Route;

Route::get('/courier-status', function () {
    return response()->json(['available' => true]);
})->middleware('acme-courier.header');

Vous pouvez aussi ne pas fournir d’alias et indiquer directement le nom de classe, par exemple ->middleware(AddCourierHeader::class). Le choix dépend de la nécessité ou non de proposer un nom court aux utilisateurs. Lorsque le package fournit lui-même des routes, indiquez explicitement les middlewares nécessaires dans le fichier de routes. loadRoutesFrom() n’ajoute pas automatiquement web ou api. Pour la méthode d’enregistrement et la gestion du cache des routes, consultez Enregistrement et cache des routes d’un package.

C’est à l’utilisateur de choisir une application à toute l’application

Pour l’appliquer à toutes les routes web de l’application, l’utilisateur ajoute la configuration suivante dans son callback withMiddleware() existant. Il ne s’agit pas d’un exemple qui remplace la configuration existante.

use Acme\Courier\Http\Middleware\AddCourierHeader;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        AddCourierHeader::class,
    ]);
})

Cette configuration utilise directement le nom de classe et ne dépend donc pas de l’ordre d’enregistrement des alias. La portée est le groupe web, et non la pile globale. Le middleware n’est pas appliqué automatiquement à api ni aux routes qui n’ont aucun de ces groupes.

Une conception qui applique le middleware à tout web dès l’installation du package et une conception où l’utilisateur l’applique explicitement ne sont pas compatibles. N’étendez pas à toutes les routes, par une mise à jour automatique, des traitements qui affectent l’authentification, les sessions, les en-têtes de réponse ou les communications externes.

Les opérations de groupe du Router diffèrent

Si le package fournit son propre groupe, utilisez un nom qui lui est propre. Voici un exemple à placer dans le boot(Router $router) du service provider.

$router->middlewareGroup('acme-courier', [
    AddCourierHeader::class,
]);

L’utilisateur peut l’appliquer avec ->middleware('acme-courier'). Toutefois, ce groupe ne contient que les classes indiquées et n’hérite ni des sessions ni de la protection CSRF de web. Il existe aussi des API pour ajouter des éléments à un groupe existant, mais l’implémentation du Router dans v13.36.0 présente les différences suivantes.

Méthode du Router	Si le groupe existe	Si le groupe n’existe pas
`middlewareGroup($name, $items)`	Remplace l’ensemble du tableau	Le crée avec le tableau indiqué
`pushMiddlewareToGroup($name, $item)`	Ajoute à la fin si l’élément n’est pas déjà présent	Crée un tableau vide puis ajoute l’élément
`prependMiddlewareToGroup($name, $item)`	Ajoute au début si l’élément n’est pas déjà présent	Ne fait rien

Si vous définissez uniquement les classes du package avec middlewareGroup('web', [...]), vous remplacez le contenu existant de web. Ne confondez pas cette méthode avec les méthodes d’ajout. De plus, appeler pushMiddlewareToGroup() sur un groupe web inexistant ne restaure pas le groupe web standard. La détection des doublons des méthodes d’ajout porte sur les valeurs enregistrées. Un alias et un nom de classe désignant la même classe sont des chaînes différentes : au stade du registre, ce sont donc des éléments distincts. Uniformisez la notation et ne supposez pas que la même classe écrite de manières différentes sera dédoublonnée lors de l’enregistrement.

L’ordre d’enregistrement ne garantit pas à lui seul l’ordre d’exécution

Le Router développe les alias et les groupes de middlewares assignés à la route, traite les exclusions, puis les trie selon leur priorité. Un simple ajout au début ou à la fin ne garantit pas un ordre strict par rapport à l’authentification ou à la liaison de modèle de route. En outre, syncMiddlewareToRouter() du HTTP Kernel synchronise les groupes détenus par le Kernel vers le Router via middlewareGroup(). Si la configuration du Kernel est resynchronisée ultérieurement, le contenu des groupes ajouté directement au Router peut être remplacé. Plutôt que de faire dépendre la modification des groupes existants de l’ordre de démarrage des packages, privilégiez une configuration centralisée dans le withMiddleware() de l’application. Pour les fonctionnalités qui exigent un ordre précis, comme après le démarrage de la session ou après l’authentification, indiquez ce prérequis dans les instructions d’installation et vérifiez-le avec la configuration des priorités de l’application. Évitez qu’un package remplace intégralement la liste des priorités de toute l’application.

Frontières entre cache et vérification

Ne placez pas l’enregistrement des alias dans une condition routesAreCached() ni dans un fichier de routes. Lorsqu’un cache existe, loadRoutesFrom() ne charge pas le fichier de routes, mais l’enregistrement reste nécessaire pour résoudre à l’exécution les alias présents dans les routes en cache. Enregistrez-les à chaque fois dans le boot() du service provider. Si vous modifiez l’assignation des routes, régénérez le cache des routes dans l’application.

php artisan route:cache
php artisan route:list --path=courier-status -vv

-vv sert à développer et vérifier le contenu des groupes. Toutefois, le succès de l’affichage de la liste ne garantit ni le traitement interne du middleware ni l’utilisation des sessions. Des tests de requêtes HTTP sont également nécessaires. Voici une méthode à ajouter à un test Feature d’une application Laravel qui définit la route /courier-status ci-dessus.

public function test_courier_header_is_applied(): void
{
    $this->get('/courier-status')
        ->assertOk()
        ->assertHeader('X-Acme-Courier', 'enabled');
}

Cas à vérifier	Résultat attendu
Route pour laquelle l’alias est seulement enregistré	L’en-tête n’est pas ajouté
Route à laquelle l’alias est assigné	L’en-tête est ajouté
Route à laquelle le nom de classe est assigné directement	Même comportement
Démarrage d’une nouvelle application après création du cache	Même comportement sur la même route
Choix d’une application à tout `web`	Appliqué aux routes `web` ciblées, sans s’étendre au-delà
Groupes et priorités propres à l’application configurés	L’ordre par rapport aux sessions, à l’authentification et aux liaisons satisfait les exigences

Les tests unitaires qui vérifient l’existence d’un groupe ou le tableau des alias et l’exécution HTTP réelle sont des vérifications distinctes. En particulier, vérifiez le cache non pas en observant simplement le Router du même processus, mais lors d’un nouveau démarrage après la création du cache. Si vous utilisez des workers de longue durée, rechargez-les en suivant votre procédure de déploiement habituelle.

Pages connexes

Middleware

Découvrez les bases de la création, de l’application aux routes, des paramètres et des priorités.

Enregistrement et cache des routes d'un package

Découvrez la relation entre le chargement des routes et la configuration lors de la création du cache.

Développement IA

Patrons de conception

Développement de packages

Structure d'application

Nouveautés Laravel 13

Eloquent approfondi

Extension de la validation

Extension de l'authentification

Sécurité

Files d'attente

Tests

Temps réel

Enregistrement et portée des middlewares d'un package

Distinguer enregistrement, application et exécution

Exposer l’alias depuis le service provider

L’utilisateur l’applique route par route

C’est à l’utilisateur de choisir une application à toute l’application

Les opérations de groupe du Router diffèrent

L’ordre d’enregistrement ne garantit pas à lui seul l’ordre d’exécution

Frontières entre cache et vérification

Pages connexes

Middleware

Enregistrement et cache des routes d'un package

Sources primaires consultées

​Distinguer enregistrement, application et exécution

​Exposer l’alias depuis le service provider

​L’utilisateur l’applique route par route

​C’est à l’utilisateur de choisir une application à toute l’application

​Les opérations de groupe du Router diffèrent

​L’ordre d’enregistrement ne garantit pas à lui seul l’ordre d’exécution

​Frontières entre cache et vérification

​Pages connexes

Middleware

Enregistrement et cache des routes d'un package

​Sources primaires consultées

Distinguer enregistrement, application et exécution

Exposer l’alias depuis le service provider

L’utilisateur l’applique route par route

C’est à l’utilisateur de choisir une application à toute l’application

Les opérations de groupe du Router diffèrent

L’ordre d’enregistrement ne garantit pas à lui seul l’ordre d’exécution

Frontières entre cache et vérification

Pages connexes

Sources primaires consultées