Packageconfiguratie samenvoegen en cachen

Als je configuratie aan je package toevoegt, worden nieuwe opties niet automatisch weggeschreven naar configuratiebestanden die gebruikers eerder hebben gepubliceerd. Om standaardwaarden aan te vullen zonder gepubliceerde configuratie te breken, moet je zowel de samenvoegstrategie voor arrays als de configuratiecache ontwerpen. Op deze pagina lees je de ServiceProvider van Laravel 13 en zie je hoe je configuratie onderhoudt als publieke API van je package. De pagina gaat uit van Laravel-packages ontwikkelen en de implementatie is gecontroleerd met v13.34.0 van laravel/framework.

Publiceren en samenvoegen zijn aparte processen

publishes() registreert een bron en een doel om te kopiëren. Tot vendor:publish het bestand kopieert, verandert de config-map van de gebruiker niet. mergeConfigFrom() werkt daarentegen de configuratierepository bij tijdens het opstarten en past het bestand zelf niet aan.

<?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
    {
        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');
    }
}

Gebruikers publiceren het configuratiebestand alleen wanneer ze het nodig hebben. Ook zonder publicatie worden bij een normale start zonder cache de standaardwaarden gebruikt via het samenvoegen in register().

php artisan vendor:publish --tag=courier-config

Als je als updatestap het configuratiebestand opnieuw publiceert met --force, overschrijf je de wijzigingen van de gebruiker. Wanneer je alleen nieuwe configuratieopties toevoegt, geef dan voorrang aan het aanvullen van standaardwaarden en het communiceren van de wijzigingen.

mergeConfigFrom() voegt alleen het hoogste niveau samen

ServiceProvider::mergeConfigFrom() voert array_merge() uit met eerst de packageconfiguratie en daarna de bestaande configuratie van de applicatie. Bij dezelfde stringsleutel krijgt de waarde van de applicatie voorrang. Het volgende voorbeeld bootst het samenvoegen door het framework na met alleen arrays.

<?php

$defaults = [
    'enabled' => true,
    'transport' => [
        'timeout' => 10,
        'retries' => 3,
    ],
];

$overrides = [
    'transport' => [
        'timeout' => 30,
    ],
];

$config = array_merge($defaults, $overrides);

var_export($config);

array (
  'enabled' => true,
  'transport' =>
  array (
    'timeout' => 30,
  ),
)

enabled op het hoogste niveau wordt aangevuld, maar transport wordt als geheel vervangen. transport.retries blijft niet behouden. Belangrijk: als de gebruiker al een oude transport-array heeft gepubliceerd, worden nieuwe sleutels die je aan diezelfde array toevoegt niet aangevuld.

Geneste configuratie aanvullen met replaceConfigRecursivelyFrom()

De ServiceProvider van Laravel 13 heeft ook de protected methode replaceConfigRecursivelyFrom(). Deze voert array_replace_recursive() uit in dezelfde volgorde. Wil je een configuratie-API waarin geneste stringsleutels afzonderlijk kunnen worden overschreven, pas dan de register() van de provider als volgt aan. Je hoeft deze voor dezelfde configuratiesleutel niet te combineren met de eerdere mergeConfigFrom().

public function register(): void
{
    $this->replaceConfigRecursivelyFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

Met de eerdere $defaults en $overrides is het resultaat als volgt.

$config = array_replace_recursive($defaults, $overrides);

var_export($config);

array (
  'enabled' => true,
  'transport' =>
  array (
    'timeout' => 30,
    'retries' => 3,
  ),
)

Configuratiecontract	Te kiezen methode	Aandachtspunt
De gebruiker geeft geneste arrays volledig op	`mergeConfigFrom()`	Niet-opgegeven sleutels binnen de array worden niet aangevuld
De gebruiker geeft slechts een deel van geneste opties op	`replaceConfigRecursivelyFrom()`	Lijsten met numerieke sleutels worden ook recursief vervangen

replaceConfigRecursivelyFrom() is een methode die bestaat in de broncode van Laravel 13 die op deze pagina is gecontroleerd. Onderscheid deze van mergeConfigFrom(), die de officiële documentatie over packageontwikkeling beschrijft, en controleer de bijbehorende frameworkimplementatie voordat je hem gebruikt.

Lijsten met numerieke sleutels worden niet volledig vervangen

Recursief vervangen is geen proces dat “de hele array door de waarde van de gebruiker vervangt”. Ook bij numerieke sleutels wordt de waarde van dezelfde sleutel vervangen en blijven sleutels die de gebruiker niet heeft opgegeven behouden.

<?php

$defaults = ['channels' => ['mail', 'database']];
$overrides = ['channels' => ['slack']];

$config = array_replace_recursive($defaults, $overrides);

var_export($config['channels']);

array (
  0 => 'slack',
  1 => 'database',
)

Ook als de gebruiker alleen ['slack'] opgeeft, blijft database staan. En als je ['channels' => []] doorgeeft, wordt de standaardlijst niet leeg. Let hier vooral op bij configuratie waarbij het opgeven van de volledige lijst betekenis heeft, zoals notificatiekanalen of middleware. Heb je zulke configuratie, kijk dan eerst naar de structuur: zet bijvoorbeeld lijsten en gedeeltelijk overschrijfbare associatieve arrays onder aparte sleutels op het hoogste niveau en gebruik ondiep samenvoegen. Als je de samenvoegmethode wijzigt in een package dat al is uitgebracht, verandert het gedrag van hetzelfde configuratiebestand. Behandel dit dus niet als een simpele vervanging van de implementatie.

De configuratiecache slaat de samengevoegde waarden op

Beide methoden slaan het samenvoegen over wanneer de applicatie CachesConfiguration implementeert en configurationIsCached() true teruggeeft. In een normale Laravel-applicatie is dat het geval bij een start waarbij een configuratiecache bestaat. ConfigCacheCommand verwijdert de oude configuratiecache, start een nieuwe applicatie op en haalt de volledige configuratierepository op. Tijdens die start wordt de configuratie van de providers samengevoegd en wordt het resultaat in het cachebestand opgeslagen. Bij volgende starts leest LoadConfiguration die waarden in. Als je het package bijwerkt en de standaardwaarden of de samenvoegmethode veranderen, wordt dat dus niet doorgevoerd in applicaties die een oude cache blijven gebruiken. Bij deployments die de configuratiecache gebruiken, bouw je de cache opnieuw op met de bijgewerkte code.

php artisan config:cache

Wil je tijdens de ontwikkeling terug naar het opnieuw inlezen uit bestanden, gebruik dan php artisan config:clear. Bepaal niet zelf waar de cache wordt aangemaakt, maar laat het beheer over aan de commando’s van Laravel.

Definieer geen Closures in configuratiebestanden. Die kunnen niet correct worden geserialiseerd door config:cache. Wil je een callback doorgeven, zet dan bijvoorbeeld een klassenaam in de configuratie en registreer de daadwerkelijke service in de provider.

Controles voordat je configuratiewijzigingen uitbrengt

Gebruik in de tests van je package niet alleen ongepubliceerde configuratie als invoer, maar ook configuratie die is overgebleven van eerdere versies.

Ook zonder gepubliceerde configuratie zijn de benodigde standaardwaarden beschikbaar.
Met oude gepubliceerde configuratie krijgen de waarden van de gebruiker voorrang en worden nieuwe opties aangevuld zoals ontworpen.
Het overschrijfcontract verandert niet voor geneste arrays, lijsten met numerieke sleutels en lege arrays.
config:cache slaagt in de gebruikende applicatie en een andere start die de cache gebruikt levert dezelfde configuratie op.

Vermeld de standaardwaarden van nieuwe sleutels en een eventueel noodzakelijke herbouw van de cache in de release notes. Bij het verwijderen of hernoemen van sleutels of het wijzigen van de samenvoegmethode weeg je ook de compatibiliteit met de gepubliceerde configuratie van gebruikers mee.

Gerelateerde pagina’s

Packages testen

Registreer de service provider en controleer het gedrag van configuratie en services.

Versiecompatibiliteit beheren

Koppel wijzigingen in de publieke API aan je releasebeleid en doorlopend onderhoud.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Packageconfiguratie samenvoegen en cachen

Publiceren en samenvoegen zijn aparte processen

mergeConfigFrom() voegt alleen het hoogste niveau samen

Geneste configuratie aanvullen met replaceConfigRecursivelyFrom()

Lijsten met numerieke sleutels worden niet volledig vervangen

De configuratiecache slaat de samengevoegde waarden op

Controles voordat je configuratiewijzigingen uitbrengt

Gerelateerde pagina’s

Packages testen

Versiecompatibiliteit beheren

Geraadpleegde primaire bronnen

​Publiceren en samenvoegen zijn aparte processen

​mergeConfigFrom() voegt alleen het hoogste niveau samen

​Geneste configuratie aanvullen met replaceConfigRecursivelyFrom()

​Lijsten met numerieke sleutels worden niet volledig vervangen

​De configuratiecache slaat de samengevoegde waarden op

​Controles voordat je configuratiewijzigingen uitbrengt

​Gerelateerde pagina’s

Packages testen

Versiecompatibiliteit beheren

​Geraadpleegde primaire bronnen

Publiceren en samenvoegen zijn aparte processen

mergeConfigFrom() voegt alleen het hoogste niveau samen

Geneste configuratie aanvullen met replaceConfigRecursivelyFrom()

Lijsten met numerieke sleutels worden niet volledig vervangen

De configuratiecache slaat de samengevoegde waarden op

Controles voordat je configuratiewijzigingen uitbrengt

Gerelateerde pagina’s

Geraadpleegde primaire bronnen