Die zuständige Laravel-Route findest du am schnellsten per Volltextsuche in routes/web.php. Das ist nur bei kleinen Anwendungen zuverlässig. Sobald API-Routen, Module, Pakete, Ressource-Routen oder dynamische Parameter beteiligt sind, zählt nicht die auffälligste Textstelle, sondern die Route, die Laravel tatsächlich registriert hat.
Genau dafür ist php artisan route:list gedacht. Ungefiltert produziert der Befehl allerdings schnell mehr Ausgabe als Erkenntnis. Mit Pfad, HTTP-Methode und ausführlicher Middleware-Anzeige wird daraus ein präzises Diagnosewerkzeug.
Den tatsächlichen Request zuerst festhalten
Bevor du einen Befehl ausführst, zerlegst du den problematischen Request in seine relevanten Bestandteile. Angenommen, diese Anfrage verhält sich unerwartet:
POST https://portal.example.test/admin/orders/418/approve?source=list
Für die Routensuche benötigst du:
- die HTTP-Methode POST,
- den Host portal.example.test,
- den Pfad admin/orders/418/approve,
- die Umgebung, in der der Fehler auftritt.
Der Query-String ?source=list gehört nicht zum Routenpfad. Er kann später für die Verarbeitung wichtig sein, entscheidet aber nicht darüber, welche normale Laravel-Route den Request entgegennimmt.
Die HTTP-Methode solltest du nicht aus der sichtbaren URL ableiten. Ein Aufruf über die Adresszeile des Browsers ist ein GET-Request. Ein Formular, ein JavaScript-Client oder ein API-Werkzeug kann dieselbe URL dagegen mit POST, PATCH oder DELETE anfragen.
route:list auf den relevanten Pfad begrenzen
Statt sämtliche registrierten Routen auszugeben, filterst du zuerst nach einem stabilen Teil des Pfads. Die konkrete Bestellnummer ist dafür ungeeignet, weil sie in der Routendefinition üblicherweise als Parameter erscheint.
php artisan route:list --path=admin/ordersLaravel kann dann beispielsweise eine URI wie admin/orders/{order}/approve anzeigen. Der Filter muss also nicht den vollständigen Request-Pfad mit seiner konkreten ID nachbilden. Ein charakteristischer Abschnitt wie orders oder admin/orders ist meist hilfreicher.
Wenn noch mehrere Treffer übrig bleiben, ergänzt du die HTTP-Methode:
php artisan route:list --path=admin/orders --method=POSTDiese Kombination beantwortet bereits die wichtigste Frage: Gibt es in der aktuell gestarteten Anwendung eine registrierte POST-Route, deren Pfad zu diesem Bereich gehört?
Action und Middleware des Treffers prüfen
Bei einem Treffer sind mehrere Spalten relevant. Die URI zeigt das registrierte Pfadmuster. Unter Action steht der Controller mit seiner Methode oder eine Closure. Der Name hilft, wenn die URL an anderer Stelle über route() erzeugt wird. Je nach Ausgabe siehst du außerdem Domain und Middleware.
Für die Fehlersuche solltest du die ausführliche Ansicht verwenden:
php artisan route:list --path=admin/orders --method=POST -v
php artisan route:list --path=admin/orders --method=POST -vvMit der ausführlichen Ausgabe werden die zugeordneten Middleware besser sichtbar. Die noch ausführlichere Variante kann Middleware-Gruppen auflösen. Damit erkennst du beispielsweise, ob die Route durch Authentifizierung, Autorisierung, eine Mandantenprüfung oder eine eigene Projekt-Middleware läuft.
Das grenzt zwei verschiedene Fehlerklassen voneinander ab: Ist die falsche Action registriert, liegt das Problem bei der Routendefinition oder ihrer Reihenfolge. Ist die richtige Action registriert, aber der Controller wird nicht erreicht, untersuchst du als Nächstes die Middleware. Ohne diese Trennung debuggt man gern im Controller, den der Request nie kennenlernen wird.
Wenn route:list keinen passenden Treffer zeigt
Eine leere gefilterte Ausgabe bedeutet nicht automatisch, dass Laravel keine Route für den Request besitzt. Häufig stimmt zunächst nur eines der Suchmerkmale nicht.
Die HTTP-Methode weicht ab
Führe den Pfadfilter einmal ohne Methodenfilter aus. Taucht die URI dann unter GET oder PATCH statt unter POST auf, hast du einen Methodenkonflikt gefunden. Prüfe anschließend den auslösenden Client. Bei HTML-Formularen kann außerdem Laravel Method Spoofing beteiligt sein: Ein Formular sendet technisch POST und übermittelt die beabsichtigte Methode über ein zusätzliches Feld.
php artisan route:list --path=admin/ordersDer Pfad enthält dynamische Parameter
Suche nicht nach der vollständigen URL mit konkreten IDs, UUIDs oder Slugs. Aus customers/8f31/orders/418 kann in der Definition customers/{customer}/orders/{order} werden. Beginne mit dem konstanten Teil des Pfads und verfeinere den Filter erst danach.
Hast du die Route identifiziert, prüfst du zusätzlich vorhandene Parameterbedingungen. Eine Route kann grundsätzlich passend aussehen und den konkreten Wert trotzdem wegen einer regulären Bedingung ablehnen, etwa wenn ausschließlich Zahlen erlaubt sind.
Die Route ist an eine Domain gebunden
Bei Domain- und Subdomain-Routen reicht der Pfad allein nicht aus. Dieselbe URI kann für verschiedene Hosts unterschiedlich registriert sein. Vergleiche deshalb die Domain-Spalte der Routenliste mit dem Host des tatsächlichen Requests. Besonders bei lokalen Umgebungen führt ein abweichender Test-Host sonst zu einer sehr überzeugenden Suche am falschen Ort.
Die Route stammt aus einem Paket
Administrationsoberflächen, Debug-Werkzeuge und andere Pakete können eigene Routen registrieren. Mit den Vendor-Filtern trennst du Anwendungs- und Paketrouten:
php artisan route:list --except-vendor
php artisan route:list --only-vendorFehlt die Route bei –except-vendor, erscheint aber unter –only-vendor, musst du nicht weiter in deinen Routendateien suchen. Dann sind die Registrierung des Pakets, dessen Konfiguration oder vorgesehene Erweiterungspunkte die passenden Ansatzstellen.
Der Routencache entspricht nicht dem erwarteten Stand
Wenn die Ausgabe nicht zu den vorhandenen Routendateien passt, kann ein aktiver Routencache die Ursache sein. In einer lokalen Entwicklungsumgebung kannst du ihn gezielt leeren und die Liste erneut erzeugen:
php artisan route:clear
php artisan route:list --path=admin/orders --method=POSTAuf einem Produktivsystem solltest du den Cache nicht spontan als Diagnose-Ritual löschen. Dort gehört das Leeren und erneute Erzeugen in den vorgesehenen Deployment-Ablauf. Entscheidend ist, dass du die Routenliste in derselben Umgebung und mit demselben Anwendungsstand prüfst, in dem der Fehler auftritt.
Mehrere passende Routen richtig einordnen
Mehrere ähnliche Treffer sind bei Ressource-Routen und dynamischen Parametern normal. Kritisch wird es, wenn zwei Routen dieselbe HTTP-Methode und überlappende Pfadmuster besitzen.
Ein typisches Beispiel ist eine statische Route wie reports/export neben einer dynamischen Route reports/{report}. Der Wert export kann grundsätzlich auch als Parameter interpretiert werden. Die Reihenfolge der Registrierung und vorhandene Parameterbedingungen entscheiden dann darüber, welcher Eintrag greift.
Vergleiche bei mehreren Kandidaten daher:
- HTTP-Methode und Domain,
- statische und dynamische Pfadsegmente,
- Reihenfolge der registrierten Routen,
- Parameterbedingungen,
- zugeordnete Middleware und Action.
Auch eine Fallback-Route verdient Aufmerksamkeit. Sie ist dafür vorgesehen, Requests aufzufangen, die keine andere Route erreicht. Taucht sie in deiner Untersuchung auffällig früh auf oder wurde sie in einem unerwarteten Modul registriert, prüfst du die Reihenfolge der beteiligten Routendateien und Service Provider.
Ein kurzer Workflow für den Supportfall
- Notiere Methode, Host und Pfad des tatsächlichen Requests.
- Führe route:list mit einem charakteristischen Pfadfragment aus.
- Grenze die Ausgabe mit –method weiter ein.
- Nutze -v oder -vv, um Action und Middleware zu prüfen.
- Vergleiche bei mehreren Treffern Domain, Parameter und Reihenfolge.
- Prüfe Cache und Paketrouten nur dann, wenn die Ausgabe weiterhin nicht zum erwarteten Anwendungsstand passt.
Erst danach lohnt sich der Sprung in Controller, Middleware oder Routendatei. Du arbeitest dann nicht mit einer Vermutung, sondern mit dem Routing-Zustand, den Laravel selbst meldet.
Fazit
Eine Laravel-Route solltest du nicht allein anhand ihres Quelltexts suchen. Die belastbare Grundlage ist die registrierte Routenliste der betroffenen Anwendung. Mit –path, –method und der ausführlichen Ausgabe wird route:list vom Übersichtskommando zum kompakten Diagnosewerkzeug.
Damit findest du nicht nur den zuständigen Controller. Du erkennst auch Methodenkonflikte, Domainbindungen, Paket-Routen, Middleware und überlappende Pfadmuster, bevor du an einer Stelle weiterarbeitest, die der Request womöglich nie erreicht.
Häufige Fragen
Kurz beantwortet, damit du schneller einschätzen kannst, was für dein Projekt wichtig ist.
Wie finde ich den Controller zu einer Laravel-URL?
Filtere die registrierten Routen mit php artisan route:list –path=pfad. In der Spalte Action siehst du den zugeordneten Controller und die aufgerufene Methode.
Kann ich route:list nach der HTTP-Methode filtern?
Ja. Ergänze beispielsweise –method=POST. Zusammen mit –path reduzierst du die Ausgabe auf die für den Request relevanten Routen.
Warum zeigt route:list meine neue Route nicht an?
Prüfe zuerst Pfad, Umgebung und HTTP-Methode. Passt die Ausgabe nicht zu den Routendateien, kann außerdem ein aktiver Routencache oder eine bedingte Routenregistrierung beteiligt sein.
Wie sehe ich die Middleware einer Laravel-Route?
Rufe route:list mit -v oder -vv auf. Die ausführliche Ausgabe zeigt die zugeordneten Middleware und kann Middleware-Gruppen detaillierter auflösen.
