Paketkonfiguration zusammenführen und cachen

Wenn Sie Ihrem Paket neue Konfigurationsoptionen hinzufügen, werden diese nicht automatisch in Konfigurationsdateien geschrieben, die Nutzer bereits früher veröffentlicht haben. Um Standardwerte zu ergänzen, ohne veröffentlichte Konfigurationen zu beschädigen, müssen Sie sowohl die Strategie zum Zusammenführen der Arrays als auch den Konfigurations-Cache bewusst gestalten. Auf dieser Seite lesen Sie den ServiceProvider von Laravel 13 und erfahren, wie Sie die Konfiguration als öffentliche API Ihres Pakets pflegen. Die Seite setzt die Grundlagen der Paketentwicklung voraus. Zur Überprüfung der Implementierung wird laravel/framework in Version v13.34.0 verwendet.

Veröffentlichen und Zusammenführen sind getrennte Vorgänge

publishes() registriert eine Quelle und ein Ziel für das Kopieren. Bis vendor:publish die Datei kopiert, bleibt das config-Verzeichnis der Nutzer unverändert. mergeConfigFrom() hingegen aktualisiert das Konfigurations-Repository beim Start der Anwendung und verändert die Datei selbst nicht.

<?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');
    }
}

Nutzer veröffentlichen die Konfigurationsdatei nur bei Bedarf. Auch ohne Veröffentlichung werden bei einem normalen Start ohne Cache die Standardwerte über das Zusammenführen in register() verwendet.

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

Wenn Sie als Update-Schritt die Konfigurationsdatei mit --force erneut veröffentlichen, werden die Änderungen der Nutzer überschrieben. Wenn Sie nur neue Konfigurationsoptionen hinzufügen, sollten Sie stattdessen Standardwerte ergänzen und auf die Änderungen hinweisen.

mergeConfigFrom() führt nur die oberste Ebene zusammen

ServiceProvider::mergeConfigFrom() übergibt zuerst die Paketkonfiguration und danach die bestehende Konfiguration der Anwendung an array_merge(). Bei gleichen String-Schlüsseln hat der Wert der Anwendung Vorrang. Das folgende Beispiel bildet den Zusammenführungsvorgang des Frameworks nur mit Arrays nach.

<?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,
  ),
)

Das oberste enabled wird ergänzt, transport wird jedoch als gesamtes Array ersetzt. transport.retries bleibt nicht erhalten. Wichtig ist: Wenn Nutzer bereits ein altes transport-Array veröffentlicht haben, werden neue Schlüssel, die Sie demselben Array hinzufügen, nicht ergänzt.

Verschachtelte Konfiguration mit replaceConfigRecursivelyFrom() ergänzen

Der ServiceProvider von Laravel 13 enthält außerdem die protected-Methode replaceConfigRecursivelyFrom(). Sie führt in derselben Reihenfolge array_replace_recursive() aus. Wenn Ihre Konfigurations-API das einzelne Überschreiben verschachtelter String-Schlüssel erlauben soll, ändern Sie register() im Provider wie folgt. Für denselben Konfigurationsschlüssel müssen Sie sie nicht zusätzlich zu mergeConfigFrom() von oben verwenden.

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

Mit den obigen $defaults und $overrides ergibt sich folgendes Ergebnis.

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

var_export($config);

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

Konfigurationsvertrag	Gewählter Vorgang	Hinweis
Nutzer geben verschachtelte Arrays vollständig an	`mergeConfigFrom()`	Nicht angegebene Schlüssel innerhalb des Arrays werden nicht ergänzt
Nutzer geben verschachtelte Einträge nur teilweise an	`replaceConfigRecursivelyFrom()`	Auch Listen mit numerischen Schlüsseln werden rekursiv ersetzt

replaceConfigRecursivelyFrom() ist eine Methode, die im auf dieser Seite geprüften Quellcode von Laravel 13 existiert. Unterscheiden Sie sie von mergeConfigFrom(), das in der offiziellen Dokumentation zur Paketentwicklung vorgestellt wird, und prüfen Sie vor der Verwendung die Implementierung der jeweiligen Framework-Version.

Listen mit numerischen Schlüsseln werden nicht vollständig ersetzt

Rekursives Ersetzen bedeutet nicht, dass das Array vollständig durch die Werte der Nutzer ausgetauscht wird. Auch bei numerischen Schlüsseln wird nur der Wert mit demselben Schlüssel ersetzt, und Schlüssel, die Nutzer nicht angegeben haben, bleiben erhalten.

<?php

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

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

var_export($config['channels']);

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

Auch wenn Nutzer nur ['slack'] angeben, bleibt database erhalten. Außerdem wird die Standardliste nicht geleert, wenn Sie ['channels' => []] übergeben. Achten Sie besonders bei Konfigurationen darauf, bei denen die Angabe der gesamten Liste eine Bedeutung hat, etwa bei Benachrichtigungszielen oder Middleware. Wenn Ihr Paket solche Konfigurationen enthält, überdenken Sie die Struktur der Konfiguration. Sie können zum Beispiel Listen und teilweise überschreibbare assoziative Arrays auf getrennte Schlüssel der obersten Ebene verteilen und flaches Zusammenführen verwenden. Wenn Sie die Zusammenführungsstrategie eines bereits veröffentlichten Pakets ändern, verhält sich dieselbe Konfigurationsdatei anders. Behandeln Sie dies daher nicht als bloßen Austausch der Implementierung.

Der Konfigurations-Cache speichert die zusammengeführten Werte

Beide Methoden überspringen das Zusammenführen, wenn die Anwendung CachesConfiguration implementiert und configurationIsCached() true zurückgibt. In einer gewöhnlichen Laravel-Anwendung trifft dies auf Starts zu, bei denen ein Konfigurations-Cache vorhanden ist. ConfigCacheCommand löscht den alten Konfigurations-Cache, startet eine neue Anwendung und ruft das gesamte Konfigurations-Repository ab. Bei diesem Start wird die Konfiguration der Provider zusammengeführt und das Ergebnis in der Cache-Datei gespeichert. Bei nachfolgenden Starts lädt LoadConfiguration diese Werte. Wenn sich also durch ein Paket-Update Standardwerte oder die Zusammenführungsstrategie ändern, wirkt sich das nicht auf Anwendungen aus, die weiterhin einen alten Cache verwenden. Bei Deployments mit Konfigurations-Cache bauen Sie den Cache mit dem aktualisierten Code neu auf.

php artisan config:cache

Wenn Sie während der Entwicklung wieder zum Laden aus den Dateien zurückkehren möchten, verwenden Sie php artisan config:clear. Legen Sie den Speicherort des Caches nicht selbst fest, sondern überlassen Sie die Verwaltung den Laravel-Befehlen.

Definieren Sie keine Closures in Konfigurationsdateien. Sie lassen sich mit config:cache nicht korrekt serialisieren. Wenn Sie einen Callback übergeben möchten, legen Sie in der Konfiguration zum Beispiel einen Klassennamen ab und registrieren den eigentlichen Service im Provider.

Prüfungen vor der Veröffentlichung von Konfigurationsänderungen

Behandeln Sie in den Tests Ihres Pakets nicht nur unveröffentlichte Konfigurationen, sondern auch Konfigurationen, die aus älteren Versionen übrig geblieben sind, als Eingabe.

Auch ohne veröffentlichte Konfiguration lassen sich die erforderlichen Standardwerte abrufen.
Bei einer alten veröffentlichten Konfiguration haben die Werte der Nutzer Vorrang, und neue Einträge werden wie vorgesehen ergänzt.
Der Überschreibungsvertrag für verschachtelte Arrays, Listen mit numerischen Schlüsseln und leere Arrays bleibt unverändert.
config:cache läuft in der nutzenden Anwendung erfolgreich, und ein separater Start mit Cache liefert dieselbe Konfiguration.

Nennen Sie in den Release Notes die Standardwerte neuer Schlüssel und einen gegebenenfalls nötigen Neuaufbau des Caches. Beim Entfernen oder Umbenennen von Schlüsseln und beim Ändern der Zusammenführungsstrategie berücksichtigen Sie auch die Kompatibilität mit den veröffentlichten Konfigurationen der Nutzer.

Pakete testen

Registrieren Sie Service Provider und überprüfen Sie das Verhalten von Konfiguration und Services.

Versionskompatibilität verwalten

Verknüpfen Sie Änderungen an der öffentlichen API mit Ihrer Release-Strategie und der laufenden Wartung.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Paketkonfiguration zusammenführen und cachen

Veröffentlichen und Zusammenführen sind getrennte Vorgänge

mergeConfigFrom() führt nur die oberste Ebene zusammen

Verschachtelte Konfiguration mit replaceConfigRecursivelyFrom() ergänzen

Listen mit numerischen Schlüsseln werden nicht vollständig ersetzt

Der Konfigurations-Cache speichert die zusammengeführten Werte

Prüfungen vor der Veröffentlichung von Konfigurationsänderungen

Verwandte Seiten

Pakete testen

Versionskompatibilität verwalten

Verwendete Primärquellen

​Veröffentlichen und Zusammenführen sind getrennte Vorgänge

​mergeConfigFrom() führt nur die oberste Ebene zusammen

​Verschachtelte Konfiguration mit replaceConfigRecursivelyFrom() ergänzen

​Listen mit numerischen Schlüsseln werden nicht vollständig ersetzt

​Der Konfigurations-Cache speichert die zusammengeführten Werte

​Prüfungen vor der Veröffentlichung von Konfigurationsänderungen

​Verwandte Seiten

Pakete testen

Versionskompatibilität verwalten

​Verwendete Primärquellen

Veröffentlichen und Zusammenführen sind getrennte Vorgänge

mergeConfigFrom() führt nur die oberste Ebene zusammen

Verschachtelte Konfiguration mit replaceConfigRecursivelyFrom() ergänzen

Listen mit numerischen Schlüsseln werden nicht vollständig ersetzt

Der Konfigurations-Cache speichert die zusammengeführten Werte

Prüfungen vor der Veröffentlichung von Konfigurationsänderungen

Verwandte Seiten

Verwendete Primärquellen