Surcharger et mettre à jour les vues d'un package

Un package qui permet aux utilisateurs de personnaliser les templates d’écrans ou d’e-mails ne doit pas se contenter de publier ses vues : il lui faut aussi un contrat qui permette de le mettre à jour tout en conservant les fichiers déjà publiés. Corriger un fichier Blade dans le package ne garantit pas que l’application qui l’utilise affiche bien ce fichier. Cette page part des bases du développement de packages et traite séparément la sélection des vues, la publication des fichiers et le cache. La documentation officielle citée est celle de Laravel 13, et l’implémentation du framework correspond à la dernière version, v13.34.0.

L’enregistrement et la publication sont deux traitements distincts

loadViewsFrom() enregistre un chemin de recherche pour un namespace. publishes() enregistre une source et une destination, mais c’est vendor:publish qui effectue réellement la copie. Dans l’exemple suivant, courier::deliveries.show est utilisable même sans publication.

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

Côté package, le fichier se trouve dans resources/views/deliveries/show.blade.php. Les points du nom de vue sont convertis en séparateurs de répertoire lors de la recherche.

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

resources/views/deliveries/show.blade.php

<p>Numéro de suivi : {{ $trackingCode }}</p>

Le namespace des vues est indépendant du nom du package Composer et du namespace PHP. Ici, c’est courier, passé en second argument de loadViewsFrom(), qui constitue le contrat pour référencer les vues et pour le répertoire de surcharge.

Rechercher la surcharge fichier par fichier

Lorsque view est résolu, ServiceProvider::loadViewsFrom() parcourt dans l’ordre les chemins de la configuration view.paths. Si un répertoire vendor/courier existe dans l’un de ces chemins, il est ajouté au namespace, puis le chemin du package est ajouté en dernier. FileViewFinder parcourt ensuite les chemins de ce namespace dans l’ordre et renvoie le premier fichier trouvé. Avec la configuration standard utilisant resources/views, l’ordre est le suivant. Il ne s’agit pas de basculer un répertoire entier. Si l’utilisateur ne surcharge que deliveries/show.blade.php, les autres vues non surchargées sont toujours chargées depuis le package.

État de l’application	Vue sélectionnée
Aucun fichier de surcharge	Fichier du package
Fichier de surcharge présent au même chemin relatif	Fichier de l’application
Seul le fichier de surcharge a été supprimé	Retour au fichier du package au démarrage suivant
Fichier cible absent des deux côtés	Exception `View [...] not found.`

Si view.paths contient plusieurs chemins, il peut aussi y avoir plusieurs emplacements de surcharge. resource_path('views/vendor/courier') n’est que la destination de publication de cet exemple, et non un traitement qui limiterait la recherche à cet emplacement. Utilisez un namespace propre au package et évitez une conception où plusieurs providers ajoutent des chemins au même nom.

Ne personnaliser que les vues nécessaires

L’utilisateur peut copier les templates avec la commande suivante. Il indique le provider et le tag pour ne pas entraîner d’autres ressources.

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

Avec cet enregistrement, tout le répertoire de vues est publié. S’il n’est pas nécessaire de tout surcharger, il est aussi possible d’examiner le contenu et de ne conserver que les fichiers à personnaliser, ou de copier manuellement uniquement les fichiers nécessaires au même chemin relatif. En effet, une copie non modifiée est elle aussi traitée comme une surcharge tant qu’elle existe.

Les templates publiés ne sont pas synchronisés automatiquement avec les mises à jour du package. Si une ancienne copie est prioritaire, corriger uniquement le package ne répercute pas les changements de cette vue. Les corrections d’affichage ou les modifications de formulaires nécessitent elles aussi une comparaison avec les fichiers de surcharge.

La republication ne fusionne pas les différences

En règle générale, VendorPublishCommand ignore la copie lorsqu’un fichier de même nom existe déjà à la destination. --force écrase les fichiers existants. Par ailleurs, --existing est lui aussi une option qui « écrase les fichiers déjà publiés » : ce n’est pas un mode qui conserve les modifications de l’utilisateur.

Opération	Effet sur les fichiers de vues
Republication ordinaire	Conserve les fichiers existants et copie les fichiers cibles absents
Publication avec `--force`	Écrase aussi les personnalisations existantes
Publication avec `--existing`	N’écrase que les fichiers cibles présents à la destination

Aucune de ces méthodes n’effectue de fusion comparant l’ancienne version, la nouvelle version et les modifications de l’utilisateur. Aucune ne supprime non plus automatiquement de la destination les vues retirées du package. Ne réduisez pas la procédure de mise à jour à « republier le même tag ».

Maintenir les vues comme une API publique

Au-delà du nom des vues, les données reçues et les éléments référencés influencent aussi les personnalisations des utilisateurs. Par exemple, si la nouvelle version renomme la variable trackingCode, les utilisateurs qui ont conservé l’ancien template ne recevront plus la valeur nécessaire depuis le nouveau code. Avant une publication, vérifiez les points de contrat suivants.

Ne pas modifier à la légère le namespace ni les noms de vues comme deliveries.show.
Documenter les variables transmises, leurs types et leur caractère obligatoire ou facultatif.
Inclure dans les changements les cibles de @include et @extends, ainsi que les props des composants Blade.
Indiquer dans les notes de version les vues modifiées et les changements à appliquer aux anciennes versions publiées.

Pour les utilisateurs, fournissez une procédure qui compare l’ancienne et la nouvelle version des vues du package et intègre manuellement les changements nécessaires dans les fichiers personnalisés. Les fichiers dont la surcharge n’est plus nécessaire peuvent être supprimés, après avoir préservé les modifications par une sauvegarde ou dans le gestionnaire de versions, pour revenir aux vues du package.

Le cache Blade ne met pas à jour les fichiers de surcharge

view:cache précompile les templates Blade en PHP. ViewCacheCommand exécute d’abord view:clear, puis rassemble les chemins de vues ordinaires et ceux enregistrés pour les namespaces afin de trouver les fichiers à compiler.

php artisan view:cache

Ce traitement ne réécrit pas les fichiers Blade publiés et ne modifie pas non plus l’ordre de priorité de la recherche des vues. Si un ancien fichier de surcharge existe, il reste sélectionné même après la reconstruction du cache. Lors d’un déploiement, compilez après avoir mis à jour le code et les fichiers de surcharge. Si vous souhaitez supprimer les fichiers compilés et forcer un nouveau rendu pendant le développement, utilisez la commande suivante.

php artisan view:clear

Lorsque la vérification habituelle des horodatages est activée, le compilateur Blade compare la date de modification du fichier source et celle du fichier compilé. Cependant, certaines configurations désactivent cette vérification : ne confiez donc pas la reconstruction lors du déploiement à la seule détection automatique.

Distinguer le cache des résultats de recherche

FileViewFinder::find() enregistre les chemins trouvés dans le tableau $views de l’instance du Finder. De plus, l’existence des répertoires de surcharge est vérifiée dans le callback de loadViewsFrom(). Ajouter un nouveau répertoire après le démarrage ne l’ajoute donc pas automatiquement aux chemins de recherche déjà enregistrés.

Élément géré	Rôle	Approche lors d’une mise à jour
Fichiers Blade publiés	Personnalisations de l’utilisateur	Intégrer les différences ou cesser la surcharge
PHP compilé	Résultat de la compilation Blade	Géré avec `view:cache` / `view:clear`
Chemins enregistrés et résultats de recherche du Finder	Sélection des vues par l’instance en cours d’exécution	Redémarrer les processus de longue durée avec le nouveau code et la nouvelle configuration

view:clear n’est pas une commande qui efface en bloc l’état du Finder conservé par d’autres processus en cours d’exécution. Pour les processus de longue durée comme Octane, rechargez-les en suivant votre procédure de déploiement habituelle. La méthode flush() du Finder efface les résultats de recherche, mais n’enregistre pas les nouveaux répertoires de surcharge.

Points à vérifier avant une publication

En plus des tests du package, vérifiez les combinaisons suivantes dans une application qui l’utilise. Un test qui ne rend que le template le plus récent ne permet pas de vérifier la compatibilité pour les utilisateurs ayant publié une ancienne version.

Sans publication, les vues du package sont rendues.
Lorsqu’un seul fichier est surchargé, seul ce fichier est prioritaire et les autres se rabattent sur le package.
Avec un ancien template publié conservé, le rendu fonctionne avec les données transmises par la nouvelle version.
Une republication ordinaire conserve les personnalisations, et l’ajout des fichiers non publiés se fait comme prévu.
Après modification d’un fichier de surcharge, view:cache réussit et l’affichage modifié apparaît au démarrage suivant.

Pages associées

Vues

Les bases de la création des vues, de la transmission de données et de la précompilation.

Templates Blade

L’utilisation des layouts, des include et des composants.

Gestion de la compatibilité des versions

Relier les changements de contrat des templates à votre politique de publication.

Octane

Le cycle de vie et le rechargement des applications de longue durée.

Développement IA

Patrons de conception

Développement de packages

Structure d'application

Nouveautés Laravel 13

Eloquent approfondi

Extension de la validation

Extension de l'authentification

Sécurité

Files d'attente

Tests

Temps réel

Surcharger et mettre à jour les vues d'un package

L’enregistrement et la publication sont deux traitements distincts

Rechercher la surcharge fichier par fichier

Ne personnaliser que les vues nécessaires

La republication ne fusionne pas les différences

Maintenir les vues comme une API publique

Le cache Blade ne met pas à jour les fichiers de surcharge

Distinguer le cache des résultats de recherche

Points à vérifier avant une publication

Pages associées

Vues

Templates Blade

Gestion de la compatibilité des versions

Octane

Sources primaires consultées

​L’enregistrement et la publication sont deux traitements distincts

​Rechercher la surcharge fichier par fichier

​Ne personnaliser que les vues nécessaires

​La republication ne fusionne pas les différences

​Maintenir les vues comme une API publique

​Le cache Blade ne met pas à jour les fichiers de surcharge

​Distinguer le cache des résultats de recherche

​Points à vérifier avant une publication

​Pages associées

Vues

Templates Blade

Gestion de la compatibilité des versions

Octane

​Sources primaires consultées

L’enregistrement et la publication sont deux traitements distincts

Rechercher la surcharge fichier par fichier

Ne personnaliser que les vues nécessaires

La republication ne fusionne pas les différences

Maintenir les vues comme une API publique

Le cache Blade ne met pas à jour les fichiers de surcharge

Distinguer le cache des résultats de recherche

Points à vérifier avant une publication

Pages associées

Sources primaires consultées