> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Enregistrement et portée des middlewares d'un package

> En analysant l'implémentation du Router de Laravel 13, découvrez comment enregistrer les alias de middleware d'un package, les appliquer explicitement, éviter d'écraser les groupes et vérifier le comportement avec le cache.

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](/fr/advanced/package-development) 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](/fr/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.

```mermaid theme={null}
flowchart TD
    A["boot du service provider"] --> B["aliasMiddleware enregistre<br>le nom et la classe"]
    C["Définition de la route"] --> D["middleware indique<br>le nom à appliquer"]
    B --> E["La route de la requête est déterminée"]
    D --> E
    E --> F["Expansion des alias et groupes<br>application des exclusions et priorités"]
    F --> G["Le Pipeline exécute les middlewares"]
```

| 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](/fr/advanced/package-discovery) ou manuellement.

```php src/Http/Middleware/AddCourierHeader.php theme={null}
<?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.

```php src/CourierServiceProvider.php theme={null}
<?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.

```php routes/web.php theme={null}
<?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](/fr/advanced/package-routes).

## 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.

```php theme={null}
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.

<Warning>
  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.
</Warning>

## 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.

```php theme={null}
$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.

```bash theme={null}
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.

```php theme={null}
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

<Columns cols={2}>
  <Card title="Middleware" icon="layer-group" href="/fr/middleware">
    Découvrez les bases de la création, de l'application aux routes, des paramètres et des priorités.
  </Card>

  <Card title="Enregistrement et cache des routes d'un package" icon="route" href="/fr/advanced/package-routes">
    Découvrez la relation entre le chargement des routes et la configuration lors de la création du cache.
  </Card>
</Columns>

## Sources primaires consultées

* [Documentation officielle de Laravel : Middleware](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/middleware.md)
* [Documentation officielle de Laravel : boot des service providers et injection de dépendances](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/providers.md#the-boot-method)
* [Router : enregistrement des alias, opérations de groupe, expansion et tri des middlewares](https://github.com/laravel/framework/blob/v13.36.0/src/Illuminate/Routing/Router.php)
* [HTTP Kernel : syncMiddlewareToRouter](https://github.com/laravel/framework/blob/v13.36.0/src/Illuminate/Foundation/Http/Kernel.php)


## Related topics

- [Enregistrement et cache des routes d'un package](/fr/advanced/package-routes.md)
- [Enregistrement des commandes Artisan d'un package et résolution des dépendances](/fr/advanced/package-commands.md)
- [Enregistrement et mise en cache des écouteurs d'événements d'un package](/fr/advanced/package-events.md)
- [Surcharge et mise à jour des traductions d'un package](/fr/advanced/package-translations.md)
- [Sujets avancés](/fr/advanced/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.