Storage-Treiber in Paketen registrieren und neu auflösen

Wenn ein Paket Speicherfunktionen bereitstellt, trennen Sie die Registrierung, wie ein Treiber erzeugt wird, von der Erzeugung der Disks des Anwenders. Wenn das bloße Booten des Providers weder externe Verbindungen aufbaut noch Dateioperationen startet, gefährden Sie den Bootvorgang in Umgebungen, die die Funktion nicht nutzen, deutlich seltener. Diese Seite basiert auf der Implementierung von Laravel Framework v13.37.0. Die Grundlagen finden Sie unter Dateispeicher, das Laden von Providern unter Automatische Paketerkennung.

Treibernamen und Disk-Namen trennen

Das erste Argument von Storage::extend() ist ein Treibername. Das Argument von Storage::disk() ist dagegen ein Disk-Name, der in filesystems.disks definiert ist. Sie können mehrere Disks definieren, die denselben Treiber verwenden.

Element	Beispiel auf dieser Seite	Aufgabe
Treibername	`acme-archive-local`	Bezeichner des Callbacks, der Disks erzeugt
Disk-Name	`reports`, `exports`	Bezeichner der Konfiguration und der erzeugten Instanz
Disk-Konfiguration	`root`, `throw` usw.	Werte, die bei der Erzeugung dieser Disk an den Callback übergeben werden

FilesystemManager::resolve() sucht nach einer eigenen Erzeugungslogik für den konfigurierten driver und ruft sie, falls vorhanden, vor den eingebauten Treibern auf. Wenn Sie local oder s3 als Erweiterungsnamen verwenden, ersetzen Sie die bestehende Erzeugungslogik. Wählen Sie daher einen paketspezifischen Namen.

Im Provider nur die Erzeugungslogik registrieren

Das folgende Minimalbeispiel verwendet die Standard-Erzeugungslogik des lokalen Laravel-Treibers wieder, um den Registrierungsweg zu veranschaulichen. Wenn Sie nur lokal speichern möchten, genügt der normale Treiber local. Wenn Sie ein eigenes Backend bereitstellen, ersetzen Sie dies wie im Beispiel der offiziellen Dokumentation durch Code, der einen Flysystem-Adapter aufbaut und ihn in Laravels FilesystemAdapter einbettet.

<?php

namespace Acme\Archive;

use Illuminate\Contracts\Foundation\Application;
use Illuminate\Filesystem\FilesystemAdapter;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\ServiceProvider;
use InvalidArgumentException;

class ArchiveServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Storage::extend('acme-archive-local', static function (
            Application $app,
            array $config,
        ): FilesystemAdapter {
            if (! is_string($config['root'] ?? null) || $config['root'] === '') {
                throw new InvalidArgumentException('Archive disk requires a root.');
            }

            return $app['filesystem']->createLocalDriver($config);
        });
    }
}

Registrieren Sie diesen Provider auf die übliche Weise im Paket. Schränken Sie die Registrierung nicht mit runningInConsole() ein, damit der Treiber in HTTP-Anfragen, Artisan und Queue-Workern verfügbar ist. Machen Sie außerdem einen Provider, der nur die Erweiterung registriert, nicht zu einem verzögerten Provider. Der Callback erhält die Anwendung und die gesamte Konfiguration der aufzulösenden Disk. Validieren Sie die Konfiguration und erzeugen Sie Clients innerhalb des Callbacks, und führen Sie in boot() keine Dateioperationen aus. createLocalDriver() im Beispiel kann bei der Erzeugung ein Verzeichnis anlegen. Deshalb ist es wichtig, Registrierungszeitpunkt und Erzeugungszeitpunkt zu trennen.

FilesystemManager::extend() bindet $this einer normalen Closure an den Manager. Gehen Sie nicht davon aus, dass Sie $this des Providers verwenden können, sondern nutzen Sie wie in diesem Beispiel eine static-Closure und das Argument $app. So bleiben die Abhängigkeiten explizit.

Anwender fügen die Konfiguration dem Array disks in config/filesystems.php hinzu.

'reports' => [
    'driver' => 'acme-archive-local',
    'root' => storage_path('app/private/reports'),
    'throw' => true,
],
'exports' => [
    'driver' => 'acme-archive-local',
    'root' => storage_path('app/private/exports'),
    'throw' => true,
],

Der aufrufende Code gibt den Disk-Namen an, nicht den Treibernamen.

use Illuminate\Support\Facades\Storage;

Storage::disk('reports')->put('summary.txt', 'Monthly summary');

Dieses Beispiel zeigt nur den Erzeugungsweg für lokale Speicherung. Die Auslieferung von Dateien über serve und das Bereitstellen temporärer URLs sind nicht Gegenstand dieser Seite. Wenn Ihr eigener Adapter URL-Erzeugung, Sichtbarkeit, Nur-Lese-Modus oder Ähnliches unterstützt, prüfen Sie die jeweilige Implementierung und die benötigten Abhängigkeitspakete. Gehen Sie nicht davon aus, dass eine Funktion schon dadurch aktiv wird, dass Sie einen Konfigurationsschlüssel übergeben.

Benannte Disks werden nach der Erzeugung vorgehalten

disk('reports') ruft den Callback nicht jedes Mal auf. Die Methode get() des Managers bevorzugt eine bereits erzeugte Instanz im internen Array $disks. Nur wenn die Disk noch nicht erzeugt wurde, läuft der Aufruf über resolve(), und das Ergebnis wird mit dem Disk-Namen als Schlüssel vorgehalten. Folglich wird eine bereits erzeugte Disk nicht automatisch aktualisiert, wenn Sie im selben Prozess Folgendes tun:

filesystems.disks.reports mit config() ändern.
Storage::extend() für denselben Treibernamen erneut aufrufen.

FilesystemServiceProvider registriert auch den Manager selbst als Singleton. Gehen Sie in lang laufenden Prozessen nicht davon aus, dass Disks für jede Anfrage oder jeden Job neu erzeugt werden.

Nach Konfigurationsänderungen nur die benötigten Disks neu auflösen

Wenn Sie im selben Prozess die Konfiguration ändern und das Ergebnis prüfen, trennen Sie die Aktualisierung der Konfiguration vom Entfernen der vorgehaltenen Disk.

use Illuminate\Support\Facades\Storage;

$before = Storage::disk('reports');

config(['filesystems.disks.reports.root' => storage_path('app/private/reports-v2')]);
Storage::forgetDisk('reports');

$after = Storage::disk('reports');

forgetDisk() entfernt den angegebenen Namen aus dem Vorhalte-Array des Managers. Der nächste Aufruf von disk() liest die aktuelle Konfiguration neu ein. In der geprüften Version entfernt auch purge() lediglich den angegebenen Namen. Es ruft keine Methode zum Schließen der Verbindung eines eigenen Backends auf.

Referenzen, die der aufrufende Code hält, wie $before, werden dadurch nicht ersetzt. Dasselbe gilt, wenn ein Singleton-Service eine alte Disk hält. Verwenden Sie forgetDisk() nicht als Mechanismus, um alle Referenzen oder andere Prozesse auf einmal zu aktualisieren.

Bei Konfigurationsänderungen und Paket-Updates in Produktion bauen Sie den Konfigurationscache im Rahmen des normalen Deployments neu auf und starten auch lang laufende Worker neu. Der Konfigurationscache und das prozessinterne Vorhalte-Array für Disks sind zwei verschiedene Dinge.

Für temporäre Konfigurationen build verwenden

Wenn Sie die gemeinsam genutzte benannte Konfiguration nicht ändern möchten, können Sie eine On-Demand-Disk verwenden.

use Illuminate\Support\Facades\Storage;

$disk = Storage::build([
    'driver' => 'acme-archive-local',
    'root' => storage_path('app/private/one-off-export'),
    'throw' => true,
]);

build() ruft resolve() direkt mit der angegebenen Konfiguration auf und fügt das Ergebnis nicht dem Vorhalte-Array der benannten Disks hinzu. Der eigene Treiber muss zwar registriert sein, aber jeder Aufruf durchläuft die Erzeugungslogik. Auch bei dynamischen Speicherorten sollten Sie das System nicht so gestalten, dass Speicherorte oder Verbindungsziele uneingeschränkt aus Benutzereingaben gewählt werden können.

Den Erzeugungsweg getrennt von fake testen

Storage::fake('reports') ersetzt diese Disk über die Methode set() des Managers durch eine lokale Test-Disk. Das ist praktisch, um Dateioperationen der Anwendung zu testen, prüft aber nicht, ob die eigene Erzeugungslogik des Pakets korrekt registriert und ausgeführt wird. Laden Sie ArchiveServiceProvider in Ihrer Testumgebung für Pakete und prüfen Sie dann die folgenden Punkte getrennt.

Test	Was geprüft wird
Normaler Boot	Wird keine Disk verwendet, starten weder Konfigurationsvalidierung noch Dateioperationen in der Erzeugungslogik
Benannte Disks	`reports` und `exports` erhalten jeweils ihre eigene Konfiguration und sind unterschiedliche Instanzen
Erneuter Abruf desselben Namens	Zwei Aufrufe von `disk('reports')` liefern dieselbe Instanz
Konfigurationsänderung	Nur die Konfiguration zu ändern, behält dieselbe Instanz bei; nach `forgetDisk()` ist es eine andere Instanz
On-Demand	Zwei Aufrufe von `build()` mit derselben Konfiguration liefern unterschiedliche Instanzen
Ungültige Konfiguration	In diesem Beispiel löst das Auflösen einer Disk ohne `root` eine Exception aus
Tatsächliches Lesen und Schreiben	Speichern, Abrufen und Löschen in einem reinen Testverzeichnis prüfen und anschließend aufräumen
Mit Konfigurationscache	Auch in einer frisch gebooteten Prüfanwendung ist der Treiber registriert und auflösbar

Bei einem eigenen externen Backend trennen Sie Erzeugungstests ohne Netzwerkzugriff von Verbindungstests in einer explizit vorbereiteten Prüfumgebung. Werten Sie einen erfolgreichen fake-Test nicht als Nachweis der Kompatibilität mit dem echten Dienst.

Checkliste für die langfristige Wartung

Dokumentieren Sie Treibername, Konfigurationsschlüssel, die API des Rückgabewerts sowie den Umgang mit Exceptions und throw als öffentliche Spezifikation.
Verwenden Sie einen Erweiterungsnamen, der nicht mit Standardtreibern oder anderen Paketen kollidiert.
Lösen Sie Disks nicht schon beim Booten des Providers auf und verwenden Sie sie dort nicht.
Unterscheiden Sie bei Konfigurationsänderungen zwischen Konfigurationscache, Vorhalte-Array des Managers, Referenzen im aufrufenden Code und anderen Prozessen.
Prüfen Sie Erzeugung, erneutes Auflösen und tatsächliche Dateioperationen fortlaufend für jede unterstützte Laravel-Version.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Storage-Treiber in Paketen registrieren und neu auflösen

Treibernamen und Disk-Namen trennen

Im Provider nur die Erzeugungslogik registrieren

Benannte Disks werden nach der Erzeugung vorgehalten

Nach Konfigurationsänderungen nur die benötigten Disks neu auflösen

Für temporäre Konfigurationen build verwenden

Den Erzeugungsweg getrennt von fake testen

Checkliste für die langfristige Wartung

Herangezogene Primärquellen

​Treibernamen und Disk-Namen trennen

​Im Provider nur die Erzeugungslogik registrieren

​Benannte Disks werden nach der Erzeugung vorgehalten

​Nach Konfigurationsänderungen nur die benötigten Disks neu auflösen

​Für temporäre Konfigurationen build verwenden

​Den Erzeugungsweg getrennt von fake testen

​Checkliste für die langfristige Wartung

​Herangezogene Primärquellen

Treibernamen und Disk-Namen trennen

Im Provider nur die Erzeugungslogik registrieren

Benannte Disks werden nach der Erzeugung vorgehalten

Nach Konfigurationsänderungen nur die benötigten Disks neu auflösen

Für temporäre Konfigurationen build verwenden

Den Erzeugungsweg getrennt von fake testen

Checkliste für die langfristige Wartung

Herangezogene Primärquellen