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

# Surcharger et mettre à jour les vues d'un package

> À partir de l'implémentation de Laravel 13, découvrez l'ordre de recherche des vues avec namespace, la maintenance des templates Blade publiés et la différence entre le cache des vues et le cache des résultats de recherche.

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

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

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.

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

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

```mermaid theme={null}
flowchart TD
    A["courier::deliveries.show"] --> B["Recherche de resources/views/vendor/courier/<br>deliveries/show.blade.php"]
    B --> C{"Le fichier existe ?"}
    C -->|Oui| D["Utilise la vue de l'application"]
    C -->|Non| E["Recherche de resources/views/<br>deliveries/show.blade.php du package"]
    E --> F{"Le fichier existe ?"}
    F -->|Oui| G["Utilise la vue du package"]
    F -->|Non| H["Exception : vue introuvable"]
```

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

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

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

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

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

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

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

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

<Columns cols={2}>
  <Card title="Vues" icon="eye" href="/fr/views">
    Les bases de la création des vues, de la transmission de données et de la précompilation.
  </Card>

  <Card title="Templates Blade" icon="code" href="/fr/blade">
    L'utilisation des layouts, des include et des composants.
  </Card>

  <Card title="Gestion de la compatibilité des versions" icon="code-branch" href="/fr/advanced/package-versioning">
    Relier les changements de contrat des templates à votre politique de publication.
  </Card>

  <Card title="Octane" icon="bolt" href="/fr/octane">
    Le cycle de vie et le rechargement des applications de longue durée.
  </Card>
</Columns>

## Sources primaires consultées

* [Documentation officielle de Laravel : vues des packages](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#views)
* [ServiceProvider : enregistrement des chemins de vues](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [FileViewFinder : ordre de recherche et conservation des résultats](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/FileViewFinder.php)
* [VendorPublishCommand : conditions de publication des fichiers](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/VendorPublishCommand.php)
* [ViewCacheCommand : collecte des chemins de vues et compilation](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewCacheCommand.php)
* [ViewClearCommand : suppression des fichiers compilés](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewClearCommand.php)
* [Compiler : vérification des dates de modification](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/Compilers/Compiler.php)


## Related topics

- [Développement de packages Laravel](/fr/advanced/package-development.md)
- [Sujets avancés](/fr/advanced/index.md)
- [Publier et mettre à jour les migrations d'un package](/fr/advanced/package-migrations.md)
- [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning.md)
- [Introduction à Vue.js — les bases pour l'utiliser avec Inertia × Laravel](/fr/blog/vue-introduction.md)


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