Middleware van packages registreren en het toepassingsbereik

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 en verwijst naar de officiële Laravel-documentatie voor 13.x en de implementatie van Framework v13.36.0. Zie 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.

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 of handmatig wordt geregistreerd.

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

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.

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

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.

routes/web.php

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

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.

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.

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.

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

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.

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

Middleware

Bekijk de basis van aanmaken, toepassen op routes, parameters en prioriteit.

Routes van packages registreren en cachen

Bekijk de relatie tussen het laden van routes en de configuratie bij het aanmaken van de cache.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Middleware van packages registreren en het toepassingsbereik

Scheid registreren, toepassen en uitvoeren

Aliassen beschikbaar maken in de provider

De gebruiker past de middleware per route toe

De gebruiker kiest voor toepassing op de hele applicatie

Groepsbewerkingen van de Router verschillen

Garandeer de uitvoeringsvolgorde niet alleen met de registratievolgorde

De grens tussen caching en controle

Gerelateerde pagina’s

Middleware

Routes van packages registreren en cachen

Geraadpleegde primaire bronnen

​Scheid registreren, toepassen en uitvoeren

​Aliassen beschikbaar maken in de provider

​De gebruiker past de middleware per route toe

​De gebruiker kiest voor toepassing op de hele applicatie

​Groepsbewerkingen van de Router verschillen

​Garandeer de uitvoeringsvolgorde niet alleen met de registratievolgorde

​De grens tussen caching en controle

​Gerelateerde pagina’s

Middleware

Routes van packages registreren en cachen

​Geraadpleegde primaire bronnen

Scheid registreren, toepassen en uitvoeren

Aliassen beschikbaar maken in de provider

De gebruiker past de middleware per route toe

De gebruiker kiest voor toepassing op de hele applicatie

Groepsbewerkingen van de Router verschillen

Garandeer de uitvoeringsvolgorde niet alleen met de registratievolgorde

De grens tussen caching en controle

Gerelateerde pagina’s

Geraadpleegde primaire bronnen