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

# Packageconfiguratie samenvoegen en cachen

> Op basis van de ServiceProvider-implementatie van Laravel 13: het verschil tussen ondiep samenvoegen en recursief vervangen, de valkuilen van arrays met numerieke sleutels en hoe je een package onderhoudt met de configuratiecache in gedachten.

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

```bash theme={null}
php artisan vendor:publish --tag=courier-config
```

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

## 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 theme={null}
<?php

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

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

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

var_export($config);
```

```text theme={null}
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()`.

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

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

```php theme={null}
$config = array_replace_recursive($defaults, $overrides);

var_export($config);
```

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

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

### 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 theme={null}
<?php

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

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

var_export($config['channels']);
```

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

```mermaid theme={null}
flowchart TD
    A["php artisan config:cache"] --> B["Oude configuratiecache verwijderen"]
    B --> C["Nieuwe applicatie opstarten"]
    C --> D["Configuratiebestanden inlezen<br>samenvoegen in providers"]
    D --> E["Volledige configuratierepository opslaan"]
    E --> F["Volgende starts gebruiken opgeslagen configuratie<br>beide samenvoegmethoden worden overgeslagen"]
```

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.

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

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

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

<Columns cols={2}>
  <Card title="Packages testen" icon="flask" href="/nl/advanced/package-testing">
    Registreer de service provider en controleer het gedrag van configuratie en services.
  </Card>

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

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: packageconfiguratie](https://github.com/laravel/docs/blob/13.x/packages.md#configuration)
* [ServiceProvider: implementatie van samenvoegen en publiceren](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [ConfigCacheCommand: de configuratiecache genereren](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ConfigCacheCommand.php)
* [LoadConfiguration: configuratie inlezen](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Bootstrap/LoadConfiguration.php)
* [ConfigClearCommand: de configuratiecache verwijderen](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ConfigClearCommand.php)


## Related topics

- [Laravel-packages ontwikkelen](/nl/advanced/package-development.md)
- [Eloquent accessors, mutators en casts](/nl/eloquent-mutators.md)
- [Laravel AI SDK](/nl/ai-sdk.md)
- [Cache](/nl/cache.md)
- [laravel/agent-skills — de officiële Laravel-collectie van AI-agentskills](/nl/blog/agent-skills-introduction.md)


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