Paket-Views überschreiben und aktualisieren

Bei einem Paket, dessen Nutzer die Templates für Seiten oder E-Mails anpassen können, reicht es nicht, die Views zu veröffentlichen. Sie brauchen auch eine Vereinbarung, wie sich das Paket aktualisieren lässt, während veröffentlichte Dateien bestehen bleiben. Wenn Sie eine Blade-Datei im Paket korrigieren, heißt das nicht unbedingt, dass die nutzende Anwendung diese Datei auch rendert. Diese Seite setzt die Grundlagen der Paketentwicklung voraus und betrachtet die Auswahl von Views, das Veröffentlichen von Dateien und das Caching getrennt voneinander. Als Referenz dienen die offizielle Dokumentation zu Laravel 13 und für die Framework-Implementierung das aktuelle Release v13.34.0.

Registrieren und Veröffentlichen sind getrennte Vorgänge

loadViewsFrom() registriert einen Suchpfad für einen Namespace. publishes() registriert Quelle und Ziel, das eigentliche Kopieren übernimmt vendor:publish. Im folgenden Beispiel können Sie courier::deliveries.show auch ohne Veröffentlichen verwenden.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}

Die Datei im Paket liegt unter resources/views/deliveries/show.blade.php. Die Punkte im View-Namen werden bei der Suche in Verzeichnistrenner umgewandelt.

return view('courier::deliveries.show', [
    'trackingCode' => 'TRACK-001',
]);

resources/views/deliveries/show.blade.php

<p>Sendungsnummer: {{ $trackingCode }}</p>

Der View-Namespace ist unabhängig vom Composer-Paketnamen und vom PHP-Namespace. Hier bildet courier, das als zweites Argument an loadViewsFrom() übergeben wird, die Vereinbarung für View-Referenzen und das Verzeichnis zum Überschreiben.

Überschreibungen werden pro Datei gesucht

ServiceProvider::loadViewsFrom() prüft beim Auflösen von view nacheinander die Pfade aus der Konfiguration view.paths. Existiert in einem Pfad ein Verzeichnis vendor/courier, wird dieses dem Namespace hinzugefügt, und zuletzt kommt der Pfad des Pakets hinzu. FileViewFinder durchsucht die Pfade dieses Namespace der Reihe nach und gibt die erste gefundene Datei zurück. Bei einer Konfiguration mit dem Standardpfad resources/views ergibt sich folgende Reihenfolge. Dabei wird nicht das gesamte Verzeichnis umgeschaltet. Überschreiben Nutzer nur deliveries/show.blade.php, werden alle anderen, nicht überschriebenen Views weiterhin aus dem Paket geladen.

Zustand der nutzenden Anwendung	Gewählte View
Keine überschreibende Datei	Datei des Pakets
Überschreibende Datei mit gleichem relativen Pfad vorhanden	Datei der nutzenden Anwendung
Nur die überschreibende Datei wurde entfernt	Bei einem neuen Start wieder die Datei des Pakets
Datei an keinem der beiden Orte vorhanden	Exception `View [...] not found.`

Bei einer Konfiguration mit mehreren view.paths kann es auch mehrere Orte zum Überschreiben geben. resource_path('views/vendor/courier') ist nur das Veröffentlichungsziel in diesem Beispiel und beschränkt die Suche nicht auf diesen Ort. Verwenden Sie einen paketspezifischen Namespace und vermeiden Sie ein Design, bei dem mehrere Provider demselben Namen Pfade hinzufügen.

Nur die benötigten Views anpassen

Nutzer können die Templates mit folgendem Befehl kopieren. Geben Sie Provider und Tag an, damit keine anderen Ressourcen mitkopiert werden.

php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider" --tag=courier-views

Mit dieser Registrierung wird das gesamte View-Verzeichnis veröffentlicht. Wenn nicht alles überschrieben werden muss, können Nutzer nach Prüfung des Inhalts nur die anzupassenden Dateien behalten oder nur die benötigten Dateien manuell unter demselben relativen Pfad ablegen. Denn auch eine unbearbeitete Kopie gilt als Überschreibung, solange sie existiert.

Veröffentlichte Templates werden bei Paket-Updates nicht automatisch synchronisiert. Solange eine alte Kopie Vorrang hat, wirkt sich eine Korrektur nur im Paket nicht auf diese View aus. Auch Fehlerbehebungen in der Darstellung oder Änderungen an Formularen müssen mit den überschreibenden Dateien abgeglichen werden.

Erneutes Veröffentlichen führt keine Änderungen zusammen

VendorPublishCommand überspringt das Kopieren normalerweise, wenn am Ziel bereits eine gleichnamige Datei existiert. --force überschreibt vorhandene Dateien. Auch --existing ist eine Option, die „bereits veröffentlichte Dateien überschreibt“, und kein Modus, der die Änderungen der Nutzer erhält.

Vorgang	Auswirkung auf View-Dateien
Normales erneutes Veröffentlichen	Vorhandene Dateien bleiben erhalten, fehlende Zieldateien werden kopiert
Veröffentlichen mit `--force`	Überschreibt auch vorhandene Anpassungen
Veröffentlichen mit `--existing`	Überschreibt nur Zieldateien, die am Ziel bereits existieren

Keine dieser Methoden ist ein Merge, der alte Version, neue Version und Änderungen der Nutzer vergleicht. Ebenso werden Views, die aus dem Paket entfernt wurden, nicht automatisch aus dem Veröffentlichungsziel gelöscht. Reduzieren Sie den Update-Ablauf daher nicht auf „denselben Tag erneut veröffentlichen“.

Views ebenfalls als öffentliche API pflegen

Nicht nur der View-Name, auch die übergebenen Daten und die referenzierten Bausteine wirken sich auf die Anpassungen der Nutzer aus. Benennen Sie in einer neuen Version zum Beispiel trackingCode in eine andere Variable um, erhalten Nutzer, die ein altes Template behalten, die benötigten Werte aus dem neuen Code nicht mehr. Prüfen Sie vor einem Release die folgenden Vereinbarungen.

Ändern Sie den Namespace und View-Namen wie deliveries.show nicht unbedacht.
Dokumentieren Sie die übergebenen Variablen, ihre Typen und ob sie Pflicht oder optional sind.
Berücksichtigen Sie auch die Ziele von @include und @extends sowie die Props von Blade-Komponenten als Änderungen.
Führen Sie in den Release Notes die geänderten Views und die Änderungen auf, die in bereits veröffentlichte alte Versionen übernommen werden sollten.

Stellen Sie Nutzern einen Ablauf bereit, mit dem sie die alte und die neue Version der Paket-Views vergleichen und die nötigen Änderungen manuell in ihre angepassten Dateien übernehmen. Dateien, deren Überschreibung nicht mehr nötig ist, können entfernt werden, nachdem die Änderungen per Backup oder Versionsverwaltung gesichert wurden. Dann wird wieder die View des Pakets verwendet.

Der Blade-Cache aktualisiert keine überschreibenden Dateien

view:cache kompiliert Blade-Templates vorab zu PHP. ViewCacheCommand führt zuerst view:clear aus und sammelt dann die normalen View-Pfade sowie die für Namespaces registrierten Pfade, um die zu kompilierenden Dateien zu finden.

php artisan view:cache

Dieser Vorgang schreibt keine veröffentlichten Blade-Dateien um und ändert auch nicht die Priorität bei der View-Suche. Existiert eine alte überschreibende Datei, wird sie auch nach dem Neuaufbau des Caches weiterhin gewählt. Kompilieren Sie beim Deployment erst, nachdem Code und überschreibende Dateien aktualisiert wurden. Wenn Sie während der Entwicklung die kompilierten Dateien löschen und neu rendern möchten, verwenden Sie folgenden Befehl.

php artisan view:clear

Ist die normale Zeitstempelprüfung aktiv, vergleicht der Blade-Compiler die Änderungszeiten der Quelldatei und der kompilierten Datei. Da sich die Zeitstempelprüfung aber auch deaktivieren lässt, sollten Sie den Neuaufbau beim Deployment nicht allein der automatischen Erkennung überlassen.

Vom Cache der Suchergebnisse unterscheiden

FileViewFinder::find() speichert gefundene Pfade im Array $views der jeweiligen Finder-Instanz. Außerdem wird das Vorhandensein des Überschreibungsverzeichnisses im Callback von loadViewsFrom() geprüft. Wird nach dem Start ein neues Verzeichnis angelegt, wird es nicht automatisch zu den bereits registrierten Suchpfaden hinzugefügt.

Verwaltetes Objekt	Rolle	Vorgehen beim Update
Veröffentlichte Blade-Dateien	Anpassungen der Nutzer	Änderungen übernehmen oder die Überschreibung aufgeben
Kompiliertes PHP	Ergebnis der Blade-Kompilierung	Mit `view:cache` / `view:clear` verwalten
Registrierte Pfade und Suchergebnisse des Finders	View-Auswahl der laufenden Instanz	Langlebige Prozesse mit neuem Code und neuer Konfiguration neu starten

view:clear ist kein Befehl, der den Finder-Zustand anderer laufender Prozesse auf einen Schlag löscht. Laden Sie langlebige Prozesse wie Octane gemäß Ihrem normalen Deployment-Ablauf neu. flush() des Finders löscht zwar die Suchergebnisse, registriert aber keine neuen Überschreibungsverzeichnisse.

Vor dem Release prüfen

Prüfen Sie zusätzlich zu den Tests des Pakets die folgenden Kombinationen in einer nutzenden Anwendung. Tests, die nur das neueste Template rendern, können die Kompatibilität für Nutzer mit bereits veröffentlichten alten Versionen nicht nachweisen.

Ohne Veröffentlichen wird die View des Pakets gerendert.
Wird nur eine Datei überschrieben, hat nur diese Datei Vorrang, alle anderen fallen auf das Paket zurück.
Auch wenn ein veröffentlichtes Template der alten Version erhalten bleibt, lässt es sich mit den Daten der neuen Version rendern.
Beim normalen erneuten Veröffentlichen bleiben Anpassungen erhalten, und nicht veröffentlichte Dateien werden wie beabsichtigt hinzugefügt.
Nach Änderungen an überschreibenden Dateien läuft view:cache erfolgreich, und nach einem neuen Start wird die geänderte Darstellung angezeigt.

Views

Grundlagen zum Erstellen von Views, zur Übergabe von Daten und zur Vorkompilierung.

Blade-Templates

Verwendung von Layouts, Includes und Komponenten.

Versionskompatibilität verwalten

Verknüpfen Sie Änderungen an Template-Vereinbarungen mit Ihrer Release-Strategie.

Octane

Lebenszyklus und Neuladen langlebiger Anwendungen.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Paket-Views überschreiben und aktualisieren

Registrieren und Veröffentlichen sind getrennte Vorgänge

Überschreibungen werden pro Datei gesucht

Nur die benötigten Views anpassen

Erneutes Veröffentlichen führt keine Änderungen zusammen

Views ebenfalls als öffentliche API pflegen

Der Blade-Cache aktualisiert keine überschreibenden Dateien

Vom Cache der Suchergebnisse unterscheiden

Vor dem Release prüfen

Verwandte Seiten

Views

Blade-Templates

Versionskompatibilität verwalten

Octane

Herangezogene Primärquellen

​Registrieren und Veröffentlichen sind getrennte Vorgänge

​Überschreibungen werden pro Datei gesucht

​Nur die benötigten Views anpassen

​Erneutes Veröffentlichen führt keine Änderungen zusammen

​Views ebenfalls als öffentliche API pflegen

​Der Blade-Cache aktualisiert keine überschreibenden Dateien

​Vom Cache der Suchergebnisse unterscheiden

​Vor dem Release prüfen

​Verwandte Seiten

Views

Blade-Templates

Versionskompatibilität verwalten

Octane

​Herangezogene Primärquellen

Registrieren und Veröffentlichen sind getrennte Vorgänge

Überschreibungen werden pro Datei gesucht

Nur die benötigten Views anpassen

Erneutes Veröffentlichen führt keine Änderungen zusammen

Views ebenfalls als öffentliche API pflegen

Der Blade-Cache aktualisiert keine überschreibenden Dateien

Vom Cache der Suchergebnisse unterscheiden

Vor dem Release prüfen

Verwandte Seiten

Herangezogene Primärquellen