Skip to main content
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 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.
src/CourierServiceProvider.php
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.
resources/views/deliveries/show.blade.php
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. 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.
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.

​
Personalizzare solo le view necessarie

L’utente può copiare i template con il comando seguente. Specifica provider e tag per non coinvolgere altre risorse.
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.
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.

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

View

Le basi della creazione delle view, del passaggio dei dati e della precompilazione.

Template Blade

Come usare layout, include e componenti.

Gestione della compatibilità tra versioni

Collega le modifiche al contratto dei template alla politica di rilascio.

Octane

Il ciclo di vita e il ricaricamento delle applicazioni di lunga durata.

​
Fonti primarie consultate

Ultima modifica il 4 ottobre 2026