> ## 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-Registrierung und Geltungsbereich in Paketen

> Erläutert anhand der Router-Implementierung von Laravel 13 die Registrierung von Middleware-Aliasen in Paketen, die explizite Anwendung, das Vermeiden des Überschreibens von Gruppen und die Prüfung beim Caching.

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

```mermaid theme={null}
flowchart TD
    A["boot des Providers"] --> B["Mit aliasMiddleware<br>Name und Klasse registrieren"]
    C["Routendefinition"] --> D["Mit middleware<br>anzuwendenden Namen angeben"]
    B --> E["Route des Requests steht fest"]
    D --> E
    E --> F["Aliase und Gruppen auflösen<br>Ausschlüsse und Priorität anwenden"]
    F --> G["Pipeline führt die Middleware aus"]
```

| 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](/de/advanced/package-discovery) oder manuell registriert wird.

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

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.

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

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.

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

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](/de/advanced/package-routes).

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

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

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

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

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

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

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

## Verwandte Seiten

<Columns cols={2}>
  <Card title="Middleware" icon="layer-group" href="/de/middleware">
    Erläutert die Grundlagen zu Erstellung, Anwendung auf Routen, Parametern und Priorität.
  </Card>

  <Card title="Paket-Routen registrieren und cachen" icon="route" href="/de/advanced/package-routes">
    Erläutert den Zusammenhang zwischen dem Laden von Routen und der Konfiguration bei der Cache-Erstellung.
  </Card>
</Columns>

## Herangezogene Primärquellen

* [Offizielle Laravel-Dokumentation: Middleware](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/middleware.md)
* [Offizielle Laravel-Dokumentation: boot und Dependency Injection in Service Providern](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/providers.md#the-boot-method)
* [Router: Alias-Registrierung, Gruppenoperationen sowie Auflösung und Sortierung von 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

- [Paket-Routen registrieren und cachen](/de/advanced/package-routes.md)
- [Vue.js – Einstieg mit Inertia × Laravel](/de/blog/vue-introduction.md)
- [React – Einstieg mit Inertia × Laravel](/de/blog/react-introduction.md)
- [Event-Listener in Paketen registrieren und cachen](/de/advanced/package-events.md)
- [Artisan-Befehle in Paketen registrieren und Abhängigkeiten auflösen](/de/advanced/package-commands.md)


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