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

# Paket-Views überschreiben und aktualisieren

> Anhand der Implementierung von Laravel 13 erläutert: die Suchreihenfolge von Views mit Namespace, die Pflege veröffentlichter Blade-Templates und der Unterschied zwischen dem View-Cache und dem Cache der Suchergebnisse.

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](/de/advanced/package-development) 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.

```php src/CourierServiceProvider.php theme={null}
<?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.

```php theme={null}
return view('courier::deliveries.show', [
    'trackingCode' => 'TRACK-001',
]);
```

```blade resources/views/deliveries/show.blade.php theme={null}
<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.

```mermaid theme={null}
flowchart TD
    A["courier::deliveries.show"] --> B["resources/views/vendor/courier/<br>deliveries/show.blade.php suchen"]
    B --> C{"Datei vorhanden?"}
    C -->|Ja| D["View der nutzenden Anwendung verwenden"]
    C -->|Nein| E["resources/views/<br>deliveries/show.blade.php im Paket suchen"]
    E --> F{"Datei vorhanden?"}
    F -->|Ja| G["View des Pakets verwenden"]
    F -->|Nein| H["Exception: View nicht gefunden"]
```

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

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

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

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

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

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

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

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

## Verwandte Seiten

<Columns cols={2}>
  <Card title="Views" icon="eye" href="/de/views">
    Grundlagen zum Erstellen von Views, zur Übergabe von Daten und zur Vorkompilierung.
  </Card>

  <Card title="Blade-Templates" icon="code" href="/de/blade">
    Verwendung von Layouts, Includes und Komponenten.
  </Card>

  <Card title="Versionskompatibilität verwalten" icon="code-branch" href="/de/advanced/package-versioning">
    Verknüpfen Sie Änderungen an Template-Vereinbarungen mit Ihrer Release-Strategie.
  </Card>

  <Card title="Octane" icon="bolt" href="/de/octane">
    Lebenszyklus und Neuladen langlebiger Anwendungen.
  </Card>
</Columns>

## Herangezogene Primärquellen

* [Offizielle Laravel-Dokumentation: Paket-Views](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#views)
* [ServiceProvider: Registrierung von View-Pfaden](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [FileViewFinder: Suchreihenfolge und Speichern von Suchergebnissen](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/FileViewFinder.php)
* [VendorPublishCommand: Bedingungen für das Veröffentlichen von Dateien](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/VendorPublishCommand.php)
* [ViewCacheCommand: Sammeln der View-Pfade und Kompilierung](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewCacheCommand.php)
* [ViewClearCommand: Löschen kompilierter Dateien](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewClearCommand.php)
* [Compiler: Prüfung der Änderungszeit](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/Compilers/Compiler.php)


## Related topics

- [Laravel-Paketentwicklung](/de/advanced/package-development.md)
- [Weiterführende Themen](/de/advanced/index.md)
- [Paket-Migrationen veröffentlichen und aktualisieren](/de/advanced/package-migrations.md)
- [Konfiguration](/de/configuration.md)
- [Versionskompatibilität von Paketen verwalten](/de/advanced/package-versioning.md)


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