Routes van packages registreren en cachen

Als een package HTTP-endpoints aanbiedt, is het niet genoeg dat de routes in de ontwikkelomgeving werken. Ze moeten zich ook volgens dezelfde afspraak gedragen nadat de applicatie van de gebruiker een routecache heeft aangemaakt. Als je de URL-prefix of het in- en uitschakelen via configuratie laat wijzigen, leg je gebruikers ook uit wanneer die wijziging van kracht wordt. Deze pagina bouwt voort op Laravel-packages ontwikkelen en behandelt de registratie en de levenscyclus van de cache als afzonderlijke onderwerpen. Als officiële documentatie is de standaardbranch 13.x van Laravel 13 gebruikt en voor de implementatie van het framework de nieuwste release v13.34.0.

loadRoutesFrom laadt alleen een bestand

ServiceProvider::loadRoutesFrom() laadt het routebestand niet als de applicatie CachesRoutes implementeert en routesAreCached() true teruggeeft. In alle andere gevallen wordt het opgegeven bestand met require geladen. De methode zelf voegt geen URI- of routenaamprefix, controller-namespace of middleware toe. Ze publiceert ook geen bestanden en voegt geen routes toe aan een bestaande cache. Het diagram gaat uit van een standaard Laravel-applicatie. Er bestaat geen aparte cache voor het package: de routes van het package maken deel uit van de routecache van de hele applicatie.

Als je het bestand in het package routes/web.php noemt, krijgt het daardoor nog geen web-middleware. Het wordt via een andere weg geladen dan de standaardroutebestanden van de applicatie, dus geef de benodigde middleware expliciet op in het package.

Configuratie en registratie scheiden

In het volgende voorbeeld maak je een openbaar endpoint dat aangeeft of het package beschikbaar is. We gaan ervan uit dat Acme\Courier\ via PSR-4 in Composer aan src/ is gekoppeld en dat de provider via automatische detectie of handmatig is geregistreerd.

config/courier.php

<?php

return [
    'routes' => [
        'enabled' => true,
        'prefix' => 'acme-courier',
    ],
];

Voeg de configuratie samen in register() en laad de routes in boot(). Maak een provider die HTTP-routes registreert geen DeferrableProvider, want dan is niet meer gegarandeerd dat de provider is opgestart op het moment dat de routes nodig zijn.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__.'/../config/courier.php', 'courier');
    }

    public function boot(): void
    {
        if (config('courier.routes.enabled')) {
            $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        }
    }
}

Deze voorwaarde bepaalt alleen of de routes worden geregistreerd. Registreert de provider ook andere services of views, plaats die dan niet binnen deze voorwaarde. Hoe je configuratie aan gebruikers publiceert en waar je op moet letten bij het samenvoegen van geneste configuratie, lees je in Packageconfiguratie samenvoegen en cachen.

routes/web.php

<?php

use Acme\Courier\Http\Controllers\StatusController;
use Illuminate\Support\Facades\Route;

Route::middleware('web')
    ->prefix(config('courier.routes.prefix'))
    ->name('acme-courier.')
    ->group(function () {
        Route::get('/status', StatusController::class)->name('status');
    });

src/Http/Controllers/StatusController.php

<?php

namespace Acme\Courier\Http\Controllers;

use Illuminate\Http\JsonResponse;

class StatusController
{
    public function __invoke(): JsonResponse
    {
        return response()->json(['available' => true]);
    }
}

De standaard-URI is /acme-courier/status en de routenaam is acme-courier.status. Als je URL’s genereert met route('acme-courier.status'), kan de aanroepende code dezelfde routenaam blijven gebruiken, ook als de URI-prefix verandert. name() op een groep plakt de strings letterlijk aan elkaar, dus geef ook de afsluitende . op.

web vervangt geen authenticatie of autorisatie. Dit voorbeeld is een openbaar endpoint zonder gevoelige gegevens. Voor endpoints die gegevens van gebruikers teruggeven, voeg je afzonderlijk authenticatiemiddleware en autorisatie toe die bij de specificatie passen.

Botsingen van URI’s en routenamen afzonderlijk voorkomen

De URI-prefix en de routenaamprefix zijn afzonderlijke mechanismen. Als je er maar één toevoegt, voorkom je geen botsingen bij de andere.

Onderdeel	Ontwerp in dit voorbeeld	Aandachtspunt bij onderhoud
URI	`acme-courier` als standaard, aanpasbaar via configuratie	Kies een waarde die niet botst met bestaande URL’s van de applicatie
Routenaam	`acme-courier.` vast	Gebruik een naam die uniek is voor het package en behoud deze als afspraak voor het genereren van URL’s
Controller	Klassereferentie gebruiken	Maak het niet afhankelijk van de controller-namespace van de applicatie
Middleware	`web` expliciet opgeven	Controleer dit samen met de middlewareconfiguratie van de doelapplicatie

Wanneer AbstractRouteCollection een routecollectie voor de cache opbouwt, gooit het een LogicException als een andere route dezelfde naam heeft. Dat je bij een normale start URL’s kon genereren, garandeert dus niet dat de routes te cachen zijn. Ook twee routes met verschillende URI’s veroorzaken een probleem als ze dezelfde naam hebben. Maak het overschrijven van routes van de applicatie via de registratievolgorde geen manier om het package uit te breiden. Bied indien nodig een instelling om de routes uit te schakelen en een service die gebruikers vanuit een eigen route kunnen aanroepen.

De configuratie bij het aanmaken van de cache blijft in de routedefinities

RouteCacheCommand voert eerst route:clear uit, start daarna een nieuwe applicatie op en verzamelt de routes. Vervolgens worden die routes serialiseerbaar gemaakt en wordt het gecompileerde resultaat naar het cachebestand geschreven. Omdat daarbij ook het routebestand van het package wordt geladen, worden de prefix en het wel of niet registreren bepaald door de configuratie op het moment dat de cache wordt aangemaakt. Bij latere starts laadt loadRoutesFrom() het bestand niet en worden de gecachte routes gebruikt.

Wijziging	Als een oude routecache blijft bestaan	Benodigde actie
Route aan het package toevoegen	De toegevoegde route verschijnt niet	Routecache opnieuw aanmaken
`routes.prefix` wijzigen	De oude URI blijft bestaan	Opnieuw aanmaken met de nieuwe configuratie
`routes.enabled` op `false` zetten	Routes in de cache verdwijnen niet	Opnieuw aanmaken met de uitgeschakelde configuratie
Package verwijderen	Definities die naar verwijderde klassen verwijzen kunnen blijven bestaan	Opnieuw aanmaken met de configuratie na verwijdering

routes.enabled is een instelling die de registratie bepaalt, geen weigering van toegang per request. Als je alleen de instelling uitschakelt terwijl een oude cache blijft bestaan, heb je het endpoint niet gestopt.

Registreer routes niet op basis van voorwaarden die per request verschillen, zoals de gebruiker of tenant. Zulke voorwaarden worden geëvalueerd in de CLI-omgeving waarin de cache wordt aangemaakt. Registreer routes met een stabiele configuratie en beslis over toegang met middleware of autorisatie in de controller.

Leg bij een deployment eerst de configuratie vast

Werk eerst de code en de configuratie bij. Gebruikt je setup de configuratiecache, maak de caches dan in de volgende volgorde opnieuw aan. Neem dit op in het deploymentproces van de applicatie.

php artisan config:cache
php artisan route:cache
php artisan route:list --name=acme-courier -vv

Als je route:cache uitvoert terwijl er nog een oude configuratiecache is, worden ook de routes met de oude configuratie aangemaakt. Alleen config:cache opnieuw uitvoeren werkt de routecache niet bij. Met -vv kun je ook de inhoud van middlewaregroepen controleren. Wil je tijdens de ontwikkeling het gedrag zonder cache controleren, wis dan zo nodig beide.

php artisan config:clear
php artisan route:clear

Routebestanden worden niet uitgevoerd bij een start met cache. Als je daar event listeners of containerbindings registreert, verandert het gedrag, dus geef routebestanden geen andere bijwerkingen dan routedefinities. In omgevingen met langlopende processen neem je het herladen na het bijwerken van de cache ook op in de normale deploymentprocedure.

Combinaties die je vóór een release controleert

Controleer naast de tests van het package de volgende combinaties in een Laravel 13-applicatie die het package gebruikt. Test niet alleen de registratie van routes in het geheugen, maar ook het pad waarin Artisan een nieuwe applicatie opstart.

Zonder cache reageert /acme-courier/status en zijn de routenaam en middleware zoals verwacht.
route:cache slaagt en ook bij een nieuwe start reageert het endpoint met dezelfde URI en routenaam.
Na het wijzigen van de prefix en het opnieuw aanmaken van de cache reageert de nieuwe URI en is de packageroute onder de oude URI verdwenen.
Na uitschakelen en het opnieuw aanmaken van de cache verschijnt de route niet in route:list --name=acme-courier.
URI’s en routenamen botsen niet met die van de applicatie of andere packages.

Als je ook het geval met een achtergebleven oude cache controleert, kun je meldingen van gebruikers reproduceren zoals “ik heb het configuratiebestand aangepast, maar de URL verandert niet”. Vermeld het opnieuw aanmaken van de cache in de upgradeprocedure en neem ook wijzigingen in routenamen en middleware mee in de beoordeling van compatibiliteit.

Gerelateerde pagina’s

Routing

Bekijk de basis van routegroepen, benoemde routes en het weergeven van routelijsten.

Packageconfiguratie samenvoegen en cachen

Bekijk updateprocedures die rekening houden met gepubliceerde configuratie en de configuratiecache.

Uitgestelde service providers

Bekijk waarom je providers die routes registreren niet uitstelt.

Versiecompatibiliteit van packages beheren

Koppel wijzigingen in de publieke API aan je releasebeleid en doorlopende controles.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Routes van packages registreren en cachen

loadRoutesFrom laadt alleen een bestand

Configuratie en registratie scheiden

Botsingen van URI’s en routenamen afzonderlijk voorkomen

De configuratie bij het aanmaken van de cache blijft in de routedefinities

Leg bij een deployment eerst de configuratie vast

Combinaties die je vóór een release controleert

Gerelateerde pagina’s

Routing

Packageconfiguratie samenvoegen en cachen

Uitgestelde service providers

Versiecompatibiliteit van packages beheren

Geraadpleegde primaire bronnen

​loadRoutesFrom laadt alleen een bestand

​Configuratie en registratie scheiden

​Botsingen van URI’s en routenamen afzonderlijk voorkomen

​De configuratie bij het aanmaken van de cache blijft in de routedefinities

​Leg bij een deployment eerst de configuratie vast

​Combinaties die je vóór een release controleert

​Gerelateerde pagina’s

Routing

Packageconfiguratie samenvoegen en cachen

Uitgestelde service providers

Versiecompatibiliteit van packages beheren

​Geraadpleegde primaire bronnen

loadRoutesFrom laadt alleen een bestand

Configuratie en registratie scheiden

Botsingen van URI’s en routenamen afzonderlijk voorkomen

De configuratie bij het aanmaken van de cache blijft in de routedefinities

Leg bij een deployment eerst de configuratie vast

Combinaties die je vóór een release controleert

Gerelateerde pagina’s

Geraadpleegde primaire bronnen