> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Routes van packages registreren en cachen

> Aan de hand van de implementatie in Laravel 13: de rol van loadRoutesFrom, het scheiden van middleware en namen, en hoe je configuratiewijzigingen in de routecache verwerkt.

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

```mermaid theme={null}
flowchart TD
    A["boot van de provider"] --> B["loadRoutesFrom aanroepen"]
    B --> C{"Is er een routecache?"}
    C -->|Nee| D["Routebestand van het package met require laden"]
    C -->|Ja| E["Laden van het packagebestand overslaan"]
    E --> F["RouteServiceProvider van Laravel<br>laadt de cache van de applicatie"]
```

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.

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

## 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](/nl/advanced/package-discovery) of handmatig is geregistreerd.

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

```php src/CourierServiceProvider.php theme={null}
<?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](/nl/advanced/package-config-merging).

```php routes/web.php theme={null}
<?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');
    });
```

```php src/Http/Controllers/StatusController.php theme={null}
<?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.

<Info>
  `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.
</Info>

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

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

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.

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

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

<Columns cols={2}>
  <Card title="Routing" icon="route" href="/nl/routing">
    Bekijk de basis van routegroepen, benoemde routes en het weergeven van routelijsten.
  </Card>

  <Card title="Packageconfiguratie samenvoegen en cachen" icon="sliders" href="/nl/advanced/package-config-merging">
    Bekijk updateprocedures die rekening houden met gepubliceerde configuratie en de configuratiecache.
  </Card>

  <Card title="Uitgestelde service providers" icon="clock" href="/nl/advanced/deferred-provider">
    Bekijk waarom je providers die routes registreren niet uitstelt.
  </Card>

  <Card title="Versiecompatibiliteit van packages beheren" icon="code-branch" href="/nl/advanced/package-versioning">
    Koppel wijzigingen in de publieke API aan je releasebeleid en doorlopende controles.
  </Card>
</Columns>

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: routes van packages](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#routes)
* [Officiële Laravel-documentatie: routing](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/routing.md)
* [ServiceProvider: implementatie van loadRoutesFrom](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [RouteServiceProvider: laden van de cache](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Support/Providers/RouteServiceProvider.php)
* [RouteCacheCommand: verzamelen en opslaan in een nieuwe applicatie](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/RouteCacheCommand.php)
* [AbstractRouteCollection: detectie van dubbele routenamen](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Routing/AbstractRouteCollection.php)


## Related topics

- [Laravel-packages ontwikkelen](/nl/advanced/package-development.md)
- [Geavanceerde onderwerpen](/nl/advanced/index.md)
- [Packageconfiguratie samenvoegen en cachen](/nl/advanced/package-config-merging.md)
- [Uitgestelde service providers](/nl/advanced/deferred-provider.md)
- [Migrations van packages publiceren en bijwerken](/nl/advanced/package-migrations.md)


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