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

# Middleware van packages registreren en het toepassingsbereik

> Op basis van de Router-implementatie van Laravel 13: middleware-aliassen van packages registreren, expliciet toepassen, het overschrijven van groepen vermijden en het gedrag met caching controleren.

Wanneer je HTTP-functionaliteit aan een package toevoegt, houd je het beschikbaar maken van middleware gescheiden van het toepassen ervan op de requests van de gebruikende applicatie. Als je het zo ontwerpt dat alleen het installeren niet het gedrag van alle routes verandert, kun je de impact bij de introductie en de toekomstige compatibiliteit beter beheersen.

Deze pagina gaat uit van de [basis van packageontwikkeling](/nl/advanced/package-development) en verwijst naar de officiële Laravel-documentatie voor `13.x` en de implementatie van Framework `v13.36.0`. Zie [Middleware](/nl/middleware) voor het schrijven van gewone middleware.

## Scheid registreren, toepassen en uitvoeren

`Router::aliasMiddleware()` registreert in een array van de Router de alias als sleutel en de klassenaam als waarde. Het maakt geen middleware-instantie aan en past niets toe op routes.

```mermaid theme={null}
flowchart TD
    A["boot van de provider"] --> B["Naam en klasse registreren<br>met aliasMiddleware"]
    C["Routedefinitie"] --> D["Toe te passen naam opgeven<br>met middleware"]
    B --> E["De route van het request wordt bepaald"]
    D --> E
    E --> F["Aliassen en groepen uitvouwen<br>uitsluitingen en prioriteit toepassen"]
    F --> G["Pipeline voert de middleware uit"]
```

| Bewerking | Rol | Wat er daarmee alleen niet gebeurt |
| - | - | - |
| `aliasMiddleware()` | Registreert de koppeling van naam naar klasse | Toepassen op requests |
| `middleware()` van een route | Wijst toe aan de betreffende route | Eigen implementatie van de middlewareklasse |
| `middlewareGroup()` | Stelt de inhoud van een benoemde groep in | Toevoegen aan globale middleware |
| Toevoegen aan de globale stack van de HTTP Kernel | Richt zich op alle requests | Ondersteuning voor uitsluiting per route |

Een aliasnaam is publieke API. Vermijd ingebouwde namen zoals `auth` of `throttle` en algemene namen die snel botsen met andere packages, en gebruik een packagespecifiek prefix. Als je dezelfde sleutel opnieuw registreert, overschrijft `aliasMiddleware()` de vorige koppeling.

## Aliassen beschikbaar maken in de provider

In het volgende voorbeeld maken we een middleware die een vaste identificatieheader aan de response toevoegt. Dit is geen voorbeeld van authenticatie, autorisatie of toegangscontrole. We gaan ervan uit dat `Acme\Courier\` via Composer PSR-4 aan `src/` is gekoppeld en dat de provider via [auto-discovery](/nl/advanced/package-discovery) of handmatig wordt geregistreerd.

```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;
    }
}
```

Gebruik de Router in `boot()`. De argumenten van `boot()` worden door de service container geïnjecteerd, dus je hoeft de `bootstrap/app.php` van de gebruiker niet automatisch aan te passen om middleware te registreren.

```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);
    }
}
```

Laat deze provider als gewone provider opstarten. Als je de aliasregistratie verplaatst naar een deferred provider die alleen wordt uitgevoerd wanneer een andere service wordt geresolved, is er geen garantie meer dat de alias geregistreerd is op het moment dat de route hem nodig heeft.

### De gebruiker past de middleware per route toe

Wijs de middleware in `routes/web.php` van de gebruikende applicatie alleen toe aan de routes die hem nodig hebben.

```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');
```

Je kunt ook geen alias aanbieden en de klassenaam direct opgeven, zoals `->middleware(AddCourierHeader::class)`. Kies op basis van de vraag of je gebruikers een korte naam moet bieden.

Ook als het package zelf routes levert, geef je de benodigde middleware expliciet op in het routebestand. `loadRoutesFrom()` voegt `web` of `api` niet automatisch toe. Zie [Routes van packages registreren en cachen](/nl/advanced/package-routes) voor de registratiemethode en de omgang met de routecache.

## De gebruiker kiest voor toepassing op de hele applicatie

Als je de middleware op alle `web`-routes van de gebruikende applicatie wilt toepassen, voegt de gebruiker de volgende instelling toe aan de bestaande `withMiddleware()`-callback. Dit is geen voorbeeld dat de bestaande instellingen vervangt.

```php theme={null}
use Acme\Courier\Http\Middleware\AddCourierHeader;
use Illuminate\Foundation\Configuration\Middleware;

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

Deze configuratie gebruikt de klassenaam direct en is dus niet afhankelijk van de volgorde van aliasregistratie. Het toepassingsbereik is de `web`-groep, niet de globale stack. De middleware wordt niet automatisch toegepast op `api` of op routes die geen van beide groepen hebben.

<Warning>
  Een ontwerp dat bij de installatie van het package op heel `web` wordt toegepast en een ontwerp waarbij de gebruiker expliciet toepast, zijn niet compatibel. Breid verwerking die invloed heeft op authenticatie, sessies, responseheaders, externe communicatie en dergelijke niet via een automatische update uit naar alle routes.
</Warning>

## Groepsbewerkingen van de Router verschillen

Als het package een eigen groep levert, gebruik dan een unieke naam. Het volgende voorbeeld plaats je in `boot(Router $router)` van de provider.

```php theme={null}
$router->middlewareGroup('acme-courier', [
    AddCourierHeader::class,
]);
```

De gebruiker kan deze toepassen met `->middleware('acme-courier')`. Deze groep bevat echter alleen de opgegeven klassen en neemt de sessie of CSRF-bescherming van `web` niet over.

Er zijn ook API's om iets aan een bestaande groep toe te voegen, maar in de Router-implementatie van `v13.36.0` zijn er de volgende verschillen.

| Methode van de Router | Als de groep bestaat | Als de groep niet bestaat |
| - | - | - |
| `middlewareGroup($name, $items)` | Vervangt de hele array | Maakt de groep met de opgegeven array |
| `pushMiddlewareToGroup($name, $item)` | Voegt achteraan toe als hetzelfde item er nog niet in staat | Maakt een lege array en voegt dan toe |
| `prependMiddlewareToGroup($name, $item)` | Voegt vooraan toe als hetzelfde item er nog niet in staat | Doet niets |

Als je met `middlewareGroup('web', [...])` alleen de klassen van het package instelt, vervang je de bestaande inhoud van `web`. Verwar dit niet met de methoden om iets toe te voegen. Ook wordt de standaard `web`-groep niet hersteld als je `pushMiddlewareToGroup()` uitvoert op een `web` die niet bestaat.

De duplicaatcontrole van de toevoegmethoden werkt op de geregistreerde waarden. Een alias en een klassenaam die naar dezelfde klasse verwijzen zijn verschillende strings, dus in de registratietabel zijn het aparte items. Gebruik een consistente schrijfwijze en ga er niet van uit dat dezelfde klasse in verschillende schrijfwijzen bij de registratie wordt ontdubbeld.

### Garandeer de uitvoeringsvolgorde niet alleen met de registratievolgorde

De Router vouwt de aliassen en groepen uit die aan een route zijn toegewezen, verwerkt de uitsluitingen en sorteert daarna op prioriteit. Alleen vooraan of achteraan toevoegen garandeert geen strikte volgorde ten opzichte van authenticatie of route model binding.

Bovendien synchroniseert `syncMiddlewareToRouter()` van de HTTP Kernel de groepen van de Kernel met `middlewareGroup()` naar de Router. Als de configuratie aan de Kernel-kant later opnieuw wordt gesynchroniseerd, kan de inhoud van groepen die je direct aan de Router hebt toegevoegd worden vervangen. Laat packages niet via hun opstartvolgorde wedijveren om bestaande groepen aan te passen, maar hanteer als uitgangspunt dat de configuratie wordt gebundeld in `withMiddleware()` van de gebruikende applicatie.

Voor functionaliteit die een bepaalde volgorde vereist, zoals na het starten van de sessie of na authenticatie, vermeld je die voorwaarde expliciet in de installatie-instructies en controleer je deze samen met de prioriteitsinstellingen van de gebruikende applicatie. Vermijd dat een package de volledige prioriteitslijst van de applicatie vervangt.

## De grens tussen caching en controle

Plaats aliasregistratie niet binnen een `routesAreCached()`-voorwaarde of in een routebestand. `loadRoutesFrom()` laadt het routebestand niet als er een cache is, maar de registratie blijft nodig om aliassen die in gecachete routes achterblijven tijdens runtime te resolven. Registreer ze elke keer in `boot()` van de provider.

Als je de toewijzing aan routes hebt gewijzigd, maak je de routecache opnieuw aan in de gebruikende applicatie.

```bash theme={null}
php artisan route:cache
php artisan route:list --path=courier-status -vv
```

`-vv` gebruik je om de inhoud van groepen uitgevouwen te controleren. Dat de lijstweergave slaagt, garandeert echter niet de verwerking binnen de middleware of het gebruik van de sessie. Tests met HTTP-requests zijn ook nodig.

Het volgende is een methode die je toevoegt aan een Feature-test van een Laravel-applicatie waarin de bovenstaande `/courier-status` is gedefinieerd.

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

| Testgeval | Verwacht resultaat |
| - | - |
| Route waarvoor alleen de alias is geregistreerd | Geen header |
| Route waaraan de alias is toegewezen | Header aanwezig |
| Route waaraan de klassenaam direct is toegewezen | Hetzelfde gedrag |
| Een nieuwe applicatie opstarten na het aanmaken van de cache | Hetzelfde gedrag op dezelfde route |
| Toepassing op heel `web` gekozen | Wordt toegepast op de betreffende `web`-routes en breidt zich niet uit naar andere |
| Eigen groepen en prioriteit van de gebruikende applicatie ingesteld | De volgorde ten opzichte van sessie, authenticatie en binding voldoet aan de eisen |

Unittests die het bestaan van groepen of de array met aliassen controleren en daadwerkelijke HTTP-uitvoering zijn afzonderlijke controles. Voer vooral de cachecontrole niet alleen uit door naar de Router in hetzelfde proces te kijken, maar met een nieuwe opstart na het aanmaken van de cache. Als je langlevende workers gebruikt, herlaad ze dan volgens je normale deploymentprocedure.

## Gerelateerde pagina's

<Columns cols={2}>
  <Card title="Middleware" icon="layer-group" href="/nl/middleware">
    Bekijk de basis van aanmaken, toepassen op routes, parameters en prioriteit.
  </Card>

  <Card title="Routes van packages registreren en cachen" icon="route" href="/nl/advanced/package-routes">
    Bekijk de relatie tussen het laden van routes en de configuratie bij het aanmaken van de cache.
  </Card>
</Columns>

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: Middleware](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/middleware.md)
* [Officiële Laravel-documentatie: boot van service providers en dependency injection](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/providers.md#the-boot-method)
* [Router: aliasregistratie, groepsbewerkingen en het uitvouwen en sorteren van middleware](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

- [Routes van packages registreren en cachen](/nl/advanced/package-routes.md)
- [Event listeners van een package registreren en cachen](/nl/advanced/package-events.md)
- [Artisan-commands van een package registreren en afhankelijkheden resolven](/nl/advanced/package-commands.md)
- [Laravel-packages ontwikkelen](/nl/advanced/package-development.md)
- [Uitgestelde service providers](/nl/advanced/deferred-provider.md)


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