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

# Sovrascrivere e aggiornare le view di un pacchetto

> Partendo dall'implementazione di Laravel 13, spiega l'ordine di ricerca delle view con namespace, la manutenzione dei template Blade pubblicati e la differenza tra la cache delle view e la cache dei risultati di ricerca.

Un pacchetto che permette agli utenti di personalizzare i template di pagine ed email non deve solo pubblicare le view: serve anche un contratto che consenta di aggiornarlo mantenendo i file già pubblicati. Correggere un file Blade nel pacchetto non garantisce che l'applicazione che lo usa stia effettivamente renderizzando quel file.

Questa pagina presuppone le [basi dello sviluppo di pacchetti](/it/advanced/package-development) e tratta separatamente la selezione delle view, la pubblicazione dei file e la cache. La documentazione ufficiale di riferimento è quella di Laravel 13, mentre per l'implementazione del framework si fa riferimento all'ultima release, `v13.34.0`.

## Registrazione e pubblicazione sono processi distinti

`loadViewsFrom()` registra un percorso di ricerca per un namespace. `publishes()` registra l'origine e la destinazione della copia, ma la copia vera e propria la esegue `vendor:publish`. Nell'esempio seguente puoi usare `courier::deliveries.show` anche senza pubblicare nulla.

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

Nel pacchetto il file si trova in `resources/views/deliveries/show.blade.php`. Durante la ricerca, i punti nel nome della view vengono convertiti in separatori di directory.

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

```blade resources/views/deliveries/show.blade.php theme={null}
<p>Numero di tracciamento: {{ $trackingCode }}</p>
```

Il namespace delle view è distinto sia dal nome del pacchetto Composer sia dal namespace PHP. Qui è `courier`, passato come secondo argomento di `loadViewsFrom()`, a costituire il contratto per i riferimenti alle view e per la directory di override.

## La destinazione dell'override si cerca file per file

`ServiceProvider::loadViewsFrom()`, quando `view` viene risolto, controlla in ordine i percorsi della configurazione `view.paths`. Se in un percorso esiste la directory `vendor/courier`, la aggiunge al namespace e, per ultimo, aggiunge il percorso del pacchetto.

`FileViewFinder` cerca in ordine nei percorsi di quel namespace e restituisce il primo file trovato. In una configurazione che usa il `resources/views` standard, l'ordine è il seguente.

```mermaid theme={null}
flowchart TD
    A["courier::deliveries.show"] --> B["Cerca resources/views/vendor/courier/<br>deliveries/show.blade.php"]
    B --> C{"Il file esiste?"}
    C -->|Sì| D["Usa la view dell'applicazione"]
    C -->|No| E["Cerca resources/views/<br>deliveries/show.blade.php del pacchetto"]
    E --> F{"Il file esiste?"}
    F -->|Sì| G["Usa la view del pacchetto"]
    F -->|No| H["Eccezione: view non trovata"]
```

Non si tratta di uno scambio dell'intera directory. Anche se l'utente sovrascrive solo `deliveries/show.blade.php`, le altre view non sovrascritte vengono caricate dal pacchetto.

| Stato dell'applicazione | View selezionata |
| - | - |
| Nessun file di override | Il file del pacchetto |
| Esiste un file di override con lo stesso percorso relativo | Il file dell'applicazione |
| È stato rimosso solo il file di override | Al nuovo avvio si torna al file del pacchetto |
| Il file non esiste in nessuna delle due posizioni | Eccezione `View [...] not found.` |

<Info>
  In una configurazione con più `view.paths`, anche le destinazioni di override possono essere più di una. `resource_path('views/vendor/courier')` è la destinazione di pubblicazione di questo esempio, non un meccanismo che limita la ricerca a quella sola directory. Usa un namespace specifico del pacchetto ed evita progetti in cui più provider aggiungono percorsi allo stesso nome.
</Info>

## Personalizzare solo le view necessarie

L'utente può copiare i template con il comando seguente. Specifica provider e tag per non coinvolgere altre risorse.

```bash theme={null}
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider" --tag=courier-views
```

Con questa registrazione viene pubblicata l'intera directory delle view. Se non serve sovrascrivere tutto, puoi controllarne il contenuto e tenere solo i file da personalizzare, oppure copiare a mano solo i file necessari nello stesso percorso relativo. Anche una copia non modificata, finché esiste, viene trattata come override.

<Warning>
  I template pubblicati non vengono sincronizzati automaticamente con gli aggiornamenti del pacchetto. Se viene data priorità a una copia vecchia, correggere solo il pacchetto non riporta la modifica in quella view. Anche le correzioni di bug di visualizzazione o le modifiche ai form richiedono un confronto con i file di override.
</Warning>

### La ripubblicazione non unisce le differenze

Di norma `VendorPublishCommand` salta la copia se esiste già un file di destinazione con lo stesso nome. `--force` sovrascrive i file esistenti. Anche `--existing` è un'opzione che "sovrascrive i file già pubblicati", non una modalità che preserva le modifiche dell'utente.

| Operazione | Effetto sui file delle view |
| - | - |
| Ripubblicazione normale | Mantiene i file esistenti e copia i file di destinazione mancanti |
| Pubblicazione con `--force` | Sovrascrive anche le personalizzazioni esistenti |
| Pubblicazione con `--existing` | Sovrascrive solo i file di destinazione già presenti |

Nessuno di questi metodi è un merge che confronta la vecchia versione, la nuova versione e le modifiche dell'utente. Nemmeno rimuove automaticamente dalla destinazione le view eliminate dal pacchetto. Non ridurre la procedura di aggiornamento a "ripubblicare lo stesso tag".

## Mantenere anche le view come API pubblica

Non solo i nomi delle view, ma anche i dati ricevuti e i componenti referenziati influiscono sulle personalizzazioni degli utenti. Per esempio, se nella nuova versione `trackingCode` viene rinominato, gli utenti che conservano il vecchio template non riceveranno più dal nuovo codice il valore di cui hanno bisogno.

Prima del rilascio verifica i seguenti contratti.

* Non modificare con leggerezza il namespace e i nomi delle view come `deliveries.show`.
* Documenta le variabili passate, i loro tipi e quali sono obbligatorie o facoltative.
* Includi tra le modifiche anche i riferimenti di `@include` e `@extends` e le props dei componenti Blade.
* Indica nelle note di rilascio le view modificate e le modifiche da applicare alle vecchie versioni già pubblicate.

Per gli utenti, prepara una procedura che confronti la vecchia e la nuova versione delle view del pacchetto e riporti a mano le modifiche necessarie nei file personalizzati. I file per cui l'override non serve più possono essere rimossi, dopo aver salvato le modifiche con un backup o con il controllo di versione, per tornare alle view del pacchetto.

## La cache di Blade non aggiorna i file di override

`view:cache` precompila i template Blade in PHP. `ViewCacheCommand` esegue prima `view:clear`, poi raccoglie i normali percorsi delle view e i percorsi registrati nei namespace per individuare cosa compilare.

```bash theme={null}
php artisan view:cache
```

Questo processo non riscrive i file Blade pubblicati né cambia la priorità di ricerca delle view. Se esiste un vecchio file di override, continuerà a essere selezionato anche dopo aver ricostruito la cache. Durante il deploy, compila dopo aver aggiornato il codice e i file di override.

Se durante lo sviluppo vuoi eliminare i file compilati e renderizzare di nuovo, usa il comando seguente.

```bash theme={null}
php artisan view:clear
```

Se il normale controllo dei timestamp è attivo, il compilatore Blade confronta l'orario di modifica del file sorgente con quello del file compilato. Tuttavia, alcune configurazioni disattivano il controllo dei timestamp, quindi non affidare la ricostruzione al momento del deploy solo al rilevamento automatico.

### Distinguerla dalla cache dei risultati di ricerca

`FileViewFinder::find()` salva il percorso trovato nell'array `$views` di quell'istanza del Finder. Inoltre, l'esistenza della directory di override viene verificata nella callback di `loadViewsFrom()`. Aggiungere una nuova directory dopo l'avvio non la inserisce automaticamente nei percorsi di ricerca già registrati.

| Elemento gestito | Ruolo | Come gestirlo durante l'aggiornamento |
| - | - | - |
| File Blade pubblicati | Personalizzazioni dell'utente | Integrare le differenze o rinunciare all'override |
| PHP compilato | Risultato della compilazione Blade | Gestirlo con `view:cache` / `view:clear` |
| Percorsi registrati e risultati di ricerca del Finder | Selezione delle view nell'istanza in esecuzione | Riavviare i processi di lunga durata con il nuovo codice e la nuova configurazione |

`view:clear` non è un comando che cancella in blocco lo stato del Finder mantenuto da altri processi in esecuzione. Con processi di lunga durata come Octane, ricaricali seguendo la normale procedura di deploy. Il metodo `flush()` del Finder cancella i risultati di ricerca, ma non registra nuove directory di override.

## Cosa verificare prima del rilascio

Oltre ai test del pacchetto, verifica le seguenti combinazioni in un'applicazione che lo usa. Un test che renderizza solo il template più recente non può verificare la compatibilità per gli utenti che hanno pubblicato una versione precedente.

* Senza pubblicazione, viene renderizzata la view del pacchetto.
* Sovrascrivendo un solo file, solo quel file ha la priorità e gli altri ricadono sul pacchetto.
* Anche mantenendo i template pubblicati della vecchia versione, il rendering funziona con i dati passati dalla nuova versione.
* La ripubblicazione normale preserva le personalizzazioni e l'aggiunta dei file non ancora pubblicati avviene come previsto.
* Dopo aver modificato i file di override, `view:cache` va a buon fine e al nuovo avvio viene mostrata la versione modificata.

## Pagine correlate

<Columns cols={2}>
  <Card title="View" icon="eye" href="/it/views">
    Le basi della creazione delle view, del passaggio dei dati e della precompilazione.
  </Card>

  <Card title="Template Blade" icon="code" href="/it/blade">
    Come usare layout, include e componenti.
  </Card>

  <Card title="Gestione della compatibilità tra versioni" icon="code-branch" href="/it/advanced/package-versioning">
    Collega le modifiche al contratto dei template alla politica di rilascio.
  </Card>

  <Card title="Octane" icon="bolt" href="/it/octane">
    Il ciclo di vita e il ricaricamento delle applicazioni di lunga durata.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: view dei pacchetti](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#views)
* [ServiceProvider: registrazione dei percorsi delle view](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [FileViewFinder: ordine di ricerca e conservazione dei risultati](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/FileViewFinder.php)
* [VendorPublishCommand: condizioni di pubblicazione dei file](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/VendorPublishCommand.php)
* [ViewCacheCommand: raccolta dei percorsi delle view e compilazione](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewCacheCommand.php)
* [ViewClearCommand: eliminazione dei file compilati](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/ViewClearCommand.php)
* [Compiler: controllo dell'orario di modifica](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/View/Compilers/Compiler.php)


## Related topics

- [Sviluppo di pacchetti Laravel](/it/advanced/package-development.md)
- [Argomenti avanzati](/it/advanced/index.md)
- [Pubblicazione e aggiornamento delle migrazioni di un pacchetto](/it/advanced/package-migrations.md)
- [Presentazione del pacchetto Blaze](/it/blog/blaze-introduction.md)
- [Localizzazione](/it/localization.md)


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