Middleware-Registrierung und Geltungsbereich in Paketen

Wenn Sie einem Paket HTTP-Funktionen hinzufügen, trennen Sie das Bereitstellen einer Middleware von ihrer Anwendung auf die Requests der nutzenden Anwendung. Ein Design, bei dem die Installation allein nicht das Verhalten aller Routen ändert, erleichtert es, die Auswirkungen bei der Einführung und die künftige Kompatibilität zu kontrollieren. Diese Seite setzt die Grundlagen der Paketentwicklung voraus und stützt sich auf die offizielle Laravel-Dokumentation 13.x sowie die Implementierung von Framework v13.36.0. Wie Sie gewöhnliche Middleware schreiben, erfahren Sie unter Middleware.

Registrierung, Anwendung und Ausführung trennen

Router::aliasMiddleware() registriert im Array des Routers den Alias als Schlüssel und den Klassennamen als Wert. Es erzeugt weder eine Instanz der Middleware noch wendet es sie auf Routen an.

Operation	Aufgabe	Was dadurch allein nicht geschieht
`aliasMiddleware()`	Registriert die Zuordnung von Name zu Klasse	Anwendung auf Requests
`middleware()` der Route	Weist die Middleware der Zielroute zu	Eigene Implementierung der Middleware-Klasse
`middlewareGroup()`	Legt den Inhalt einer benannten Gruppe fest	Hinzufügen zur globalen Middleware
Hinzufügen zum globalen Stack des HTTP-Kernels	Erfasst alle Requests	Unterstützung von Ausschlüssen pro Route

Der Aliasname ist eine öffentliche API. Vermeiden Sie eingebaute Namen wie auth oder throttle sowie allgemeine Namen, die leicht mit anderen Paketen kollidieren, und verwenden Sie ein paketspezifisches Präfix. Wenn Sie denselben Schlüssel erneut registrieren, überschreibt aliasMiddleware() die vorherige Zuordnung.

Aliase im Provider bereitstellen

Im folgenden Beispiel erstellen wir eine Middleware, die der Response einen festen Identifikations-Header hinzufügt. Es handelt sich nicht um ein Beispiel für Authentifizierung, Autorisierung oder Zugriffskontrolle. Vorausgesetzt wird, dass Acme\Courier\ per PSR-4 in Composer auf src/ abgebildet ist und der Provider per automatischer Erkennung oder manuell registriert wird.

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

Den Router verwenden Sie in boot(). Da die Argumente von boot() aus dem Service Container injiziert werden, müssen Sie zur Registrierung der Middleware nicht automatisch die bootstrap/app.php des Nutzers bearbeiten.

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

Starten Sie diesen Provider als gewöhnlichen Provider. Wenn Sie die Alias-Registrierung in einen Deferred Provider verschieben, der nur bei der Auflösung eines anderen Service ausgeführt wird, ist nicht mehr garantiert, dass der Alias registriert ist, wenn die Route ihn benötigt.

Der Nutzer wendet die Middleware pro Route an

In routes/web.php der nutzenden Anwendung weisen Sie die Middleware nur den Routen zu, die sie benötigen.

routes/web.php

<?php

use Illuminate\Support\Facades\Route;

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

Sie können auch auf einen Alias verzichten und den Klassennamen direkt angeben, etwa mit ->middleware(AddCourierHeader::class). Entscheiden Sie danach, ob Sie den Nutzern einen kurzen Namen bereitstellen müssen. Auch wenn das Paket selbst Routen bereitstellt, geben Sie die benötigte Middleware in der Routendatei explizit an. loadRoutesFrom() fügt web oder api nicht automatisch hinzu. Zur Registrierung und zum Umgang mit dem Routen-Cache siehe Paket-Routen registrieren und cachen.

Die Anwendung auf die gesamte Anwendung wählt der Nutzer

Soll die Middleware auf alle web-Routen der nutzenden Anwendung angewendet werden, fügt der Nutzer dem bestehenden withMiddleware()-Callback die folgende Konfiguration hinzu. Das Beispiel ersetzt keine bestehende Konfiguration.

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

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

Da diese Konfiguration den Klassennamen direkt verwendet, hängt sie nicht von der Reihenfolge der Alias-Registrierung ab. Der Geltungsbereich ist die web-Gruppe, nicht der globale Stack. Auf api oder Routen, die keiner der beiden Gruppen angehören, wird die Middleware nicht automatisch angewendet.

Ein Design, das die Middleware bei der Installation des Pakets auf ganz web anwendet, und ein Design, bei dem der Nutzer sie explizit anwendet, sind nicht kompatibel. Weiten Sie Verarbeitungen, die Authentifizierung, Sessions, Response-Header, externe Kommunikation usw. beeinflussen, nicht durch automatische Updates auf alle Routen aus.

Die Gruppenoperationen des Routers unterscheiden sich

Wenn ein Paket eine eigene Gruppe bereitstellt, verwenden Sie einen eindeutigen Namen. Das folgende Beispiel gehört in boot(Router $router) des Providers.

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

Nutzer können sie mit ->middleware('acme-courier') anwenden. Diese Gruppe enthält jedoch nur die angegebenen Klassen und übernimmt weder die Session noch den CSRF-Schutz von web. Es gibt auch APIs, um bestehenden Gruppen Einträge hinzuzufügen, doch in der Router-Implementierung von v13.36.0 bestehen folgende Unterschiede.

Router-Methode	Wenn die Gruppe existiert	Wenn die Gruppe nicht existiert
`middlewareGroup($name, $items)`	Ersetzt das gesamte Array	Erstellt sie mit dem angegebenen Array
`pushMiddlewareToGroup($name, $item)`	Fügt am Ende hinzu, sofern der Eintrag noch nicht vorhanden ist	Erstellt ein leeres Array und fügt dann hinzu
`prependMiddlewareToGroup($name, $item)`	Fügt am Anfang hinzu, sofern der Eintrag noch nicht vorhanden ist	Tut nichts

Wenn Sie mit middlewareGroup('web', [...]) nur die Klassen des Pakets festlegen, ersetzen Sie den bestehenden Inhalt von web. Verwechseln Sie dies nicht mit den Methoden zum Hinzufügen. Außerdem wird die Standardgruppe web nicht wiederhergestellt, wenn Sie pushMiddlewareToGroup() auf ein nicht vorhandenes web anwenden. Die Duplikatprüfung der Methoden zum Hinzufügen bezieht sich auf die registrierten Werte. Ein Alias und ein Klassenname, die auf dieselbe Klasse verweisen, sind unterschiedliche Strings und gelten in der Registrierungstabelle daher als getrennte Einträge. Vereinheitlichen Sie die Schreibweise und gehen Sie nicht davon aus, dass dieselbe Klasse in unterschiedlicher Schreibweise bei der Registrierung dedupliziert wird.

Die Registrierungsreihenfolge allein garantiert keine Ausführungsreihenfolge

Der Router löst die der Route zugewiesenen Middleware-Aliase und -Gruppen auf, verarbeitet die Ausschlüsse und sortiert anschließend nach Priorität. Das Hinzufügen am Anfang oder Ende allein garantiert keine exakte Reihenfolge gegenüber Authentifizierung oder Route Model Binding. Zudem synchronisiert syncMiddlewareToRouter() des HTTP-Kernels die Gruppen des Kernels per middlewareGroup() in den Router. Wird die Konfiguration auf Kernel-Seite später erneut synchronisiert, kann der Inhalt von Gruppen, die Sie direkt im Router ergänzt haben, ersetzt werden. Anstatt über die Startreihenfolge der Pakete um Änderungen an bestehenden Gruppen zu konkurrieren, sollte die Konfiguration grundsätzlich in withMiddleware() der nutzenden Anwendung gebündelt werden. Bei Funktionen, die eine bestimmte Reihenfolge erfordern, etwa nach dem Start der Session oder nach der Authentifizierung, dokumentieren Sie diese Voraussetzung in der Installationsanleitung und prüfen sie zusammen mit der Prioritätskonfiguration der nutzenden Anwendung. Vermeiden Sie, dass ein Paket die Prioritätsliste der gesamten Anwendung vollständig ersetzt.

Grenzen von Cache und Prüfung

Platzieren Sie die Alias-Registrierung nicht innerhalb einer routesAreCached()-Bedingung oder in Routendateien. loadRoutesFrom() lädt bei vorhandenem Cache keine Routendateien, doch die Registrierung wird weiterhin benötigt, um die in den gecachten Routen verbleibenden Aliase zur Laufzeit aufzulösen. Registrieren Sie sie bei jedem Start in boot() des Providers. Wenn Sie die Zuweisung zu Routen ändern, erstellen Sie den Routen-Cache in der nutzenden Anwendung neu.

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

-vv verwenden Sie, um den Inhalt der Gruppen aufgelöst zu prüfen. Eine erfolgreiche Listenausgabe garantiert jedoch weder die Verarbeitung innerhalb der Middleware noch die Nutzung der Session. HTTP-Request-Tests sind ebenfalls erforderlich. Die folgende Methode ergänzen Sie in einem Feature-Test einer Laravel-Anwendung, die das obige /courier-status definiert.

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

Prüffall	Erwartetes Ergebnis
Route, für die nur der Alias registriert wurde	Der Header wird nicht gesetzt
Route, der der Alias zugewiesen ist	Der Header wird gesetzt
Route, der der Klassenname direkt zugewiesen ist	Gleiches Verhalten
Neue Anwendung nach Erstellung des Caches gestartet	Gleiches Verhalten bei derselben Route
Anwendung auf ganz `web` gewählt	Wird auf die betroffenen `web`-Routen angewendet und nicht darüber hinaus ausgeweitet
Eigene Gruppen und Prioritäten der nutzenden Anwendung konfiguriert	Die Reihenfolge gegenüber Session, Authentifizierung und Binding erfüllt die Anforderungen

Unit-Tests, die das Vorhandensein von Gruppen oder das Alias-Array prüfen, und die tatsächliche HTTP-Ausführung sind getrennte Prüfungen. Insbesondere die Cache-Prüfung führen Sie nicht nur durch Betrachten des Routers im selben Prozess durch, sondern mit einem neuen Start nach der Erstellung des Caches. Wenn Sie langlebige Worker verwenden, laden Sie sie gemäß Ihrem üblichen Deployment-Ablauf neu.

Middleware

Erläutert die Grundlagen zu Erstellung, Anwendung auf Routen, Parametern und Priorität.

Paket-Routen registrieren und cachen

Erläutert den Zusammenhang zwischen dem Laden von Routen und der Konfiguration bei der Cache-Erstellung.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Middleware-Registrierung und Geltungsbereich in Paketen

Registrierung, Anwendung und Ausführung trennen

Aliase im Provider bereitstellen

Der Nutzer wendet die Middleware pro Route an

Die Anwendung auf die gesamte Anwendung wählt der Nutzer

Die Gruppenoperationen des Routers unterscheiden sich

Die Registrierungsreihenfolge allein garantiert keine Ausführungsreihenfolge

Grenzen von Cache und Prüfung

Verwandte Seiten

Middleware

Paket-Routen registrieren und cachen

Herangezogene Primärquellen

​Registrierung, Anwendung und Ausführung trennen

​Aliase im Provider bereitstellen

​Der Nutzer wendet die Middleware pro Route an

​Die Anwendung auf die gesamte Anwendung wählt der Nutzer

​Die Gruppenoperationen des Routers unterscheiden sich

​Die Registrierungsreihenfolge allein garantiert keine Ausführungsreihenfolge

​Grenzen von Cache und Prüfung

​Verwandte Seiten

Middleware

Paket-Routen registrieren und cachen

​Herangezogene Primärquellen

Registrierung, Anwendung und Ausführung trennen

Aliase im Provider bereitstellen

Der Nutzer wendet die Middleware pro Route an

Die Anwendung auf die gesamte Anwendung wählt der Nutzer

Die Gruppenoperationen des Routers unterscheiden sich

Die Registrierungsreihenfolge allein garantiert keine Ausführungsreihenfolge

Grenzen von Cache und Prüfung

Verwandte Seiten

Herangezogene Primärquellen