Asset pubblici e aggiornamento di un pacchetto

Anche se aggiorni il JavaScript o il CSS di un pacchetto, i file già copiati nella cartella public dell’applicazione non cambiano automaticamente. Per evitare che solo il codice PHP passi alla nuova versione mentre il browser continua a usare gli asset della versione precedente, devi stabilire chi è il proprietario della destinazione di pubblicazione e quale procedura di aggiornamento seguire. Questa pagina presuppone le basi dello sviluppo di pacchetti e, partendo dal processo di pubblicazione di Laravel 13, organizza la progettazione della distribuzione e della manutenzione. Per verificare l’implementazione è stata usata la versione v13.35.0 di laravel/framework.

La pubblicazione non è né una build né una sincronizzazione

ServiceProvider::publishes() registra un’origine e una destinazione di copia. È vendor:publish a copiare effettivamente i file. Non esegue la transpilazione del JavaScript, la build del CSS né l’aggiunta agli entry point Vite dell’applicazione. Se il pacchetto distribuisce file già compilati, puoi usare per esempio la struttura seguente.

courier/
├── public/
│   ├── courier.css
│   └── courier.js
└── src/
    └── CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__.'/../public' => public_path('vendor/courier'),
            ], 'courier-assets');
        }
    }
}

Alla prima pubblicazione, specifica esplicitamente il provider e il tag.

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

In questo esempio vengono creati public/vendor/courier/courier.css e courier.js. Se il pacchetto è progettato per distribuirli come normali file CSS e JavaScript, puoi referenziarli da Blade in questo modo.

<link rel="stylesheet" href="{{ asset('vendor/courier/courier.css') }}">
<script src="{{ asset('vendor/courier/courier.js') }}" defer></script>

Se li distribuisci come ES modules o in altri formati, adatta il modo di caricarli al formato di distribuzione. asset() è un helper che genera URL: non esegue build, pubblicazione né generazione di nomi di file basati sul contenuto.

Nell’origine della copia inserisci solo artefatti di build che possono essere resi pubblici. In questo esempio la destinazione è public, accessibile dal web. Non includere file di configurazione o dati interni nello stesso gruppo di pubblicazione.

I tag non sono namespace riservati al provider

ServiceProvider registra i percorsi di pubblicazione in un array per classe di provider e in un array per tag. L’array per tag è condiviso tra più provider, quindi se usi un tag generico come public potrebbero essere coinvolti anche altri pacchetti.

Opzione	Percorsi di pubblicazione selezionati
`--tag=courier-assets`	I percorsi di tutti i provider che hanno registrato quel tag
`--provider="Acme\Courier\CourierServiceProvider"`	Tutti i percorsi registrati da quel provider
Provider e tag insieme	L’intersezione tra i percorsi del provider e quelli del tag
`--all`	I percorsi di pubblicazione di tutti i provider

Quando specifichi entrambi, pathsForProviderAndGroup() usa array_intersect_key() con il percorso di origine come chiave. Non è un meccanismo per passare a una destinazione diversa in base al tag. Evita di registrare più volte la stessa origine per associarle destinazioni diverse a seconda dell’uso. --tag può essere ripetuto: in quel caso ogni tag viene pubblicato in sequenza. --all ritorna all’inizio del processo di selezione, quindi anche se aggiungi contemporaneamente --provider o --tag, questi non vengono usati per restringere la selezione.

Per non sovrascrivere anche la configurazione e le view degli utenti, nella procedura di aggiornamento usa un tag degli asset specifico del pacchetto. Se specifichi solo il provider e aggiungi --force, potrebbero essere coinvolte anche la configurazione e le view dello stesso provider.

Scegliere le opzioni di ripubblicazione

Nella pubblicazione di file e di directory, VendorPublishCommand decide se copiare in base all’esistenza del file di destinazione e alle opzioni. La tabella seguente descrive il comportamento per i normali file di asset presenti nell’origine.

Opzione	File non presente nella destinazione	File presente nella destinazione
Nessuna	Viene aggiunto	Viene mantenuto
`--force`	Viene aggiunto	Viene sovrascritto
`--existing`	Non viene aggiunto	Viene sovrascritto
`--existing --force`	Non viene aggiunto	Viene sovrascritto

--existing non è un’opzione che protegge le modifiche. Sovrascrive i file esistenti, ma non pubblica i file aggiunti nella nuova versione. Negli aggiornamenti in cui il JavaScript richiede nuovi file aggiuntivi, con il solo --existing gli artefatti potrebbero risultare incompleti. Se il contratto prevede che la destinazione sia gestita dal pacchetto e che gli utenti non la modifichino direttamente, dopo l’aggiornamento esegui il comando seguente.

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

--force non unisce le differenze e sovrascrive anche le modifiche degli utenti. Separa il CSS personalizzato dagli utenti dagli artefatti gestiti dal pacchetto, per esempio caricandolo come file distinto. Mantieni una politica di aggiornamento diversa da quella per la personalizzazione della configurazione e delle view.

I file eliminati restano nella destinazione

moveManagedFiles(), usato nella pubblicazione di directory, scorre i file presenti nell’origine e li scrive. Non esiste un processo che cerchi ed elimini i file presenti solo nella destinazione. Nemmeno --force esegue una sincronizzazione completa della directory. Per esempio, anche se elimini legacy.js nella nuova versione, public/vendor/courier/legacy.js resta se avevi già pubblicato la versione precedente. Anche in caso di rinomina il file con il vecchio nome resta, quindi nelle note di rilascio registra i file eliminati o rinominati e le modifiche ai riferimenti. Se fornisci una procedura per rimuovere i vecchi file, indica in modo specifico i file di proprietà del pacchetto. Non proporre una procedura che elimini per intero una directory in cui potrebbero trovarsi file propri degli utenti.

Aderire a laravel-assets significa accettare un contratto di sovrascrittura

Lo scheletro ufficiale delle applicazioni Laravel 13 contiene il seguente script in post-update-cmd di composer.json.

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

Si tratta di uno script dell’applicazione. Non è l’auto-discovery dei pacchetti ad aggiornare i file pubblicati. Nelle applicazioni esistenti lo script potrebbe essere stato modificato o rimosso, quindi verifica la configurazione lato utente. Per aderire a questo percorso di aggiornamento, trasforma in array il secondo argomento del publishes() visto prima e registra gli stessi asset sotto due tag.

$this->publishes([
    __DIR__.'/../public' => public_path('vendor/courier'),
], ['courier-assets', 'laravel-assets']);

laravel-assets non è un tag con un processo di copia speciale. Poiché lo script dello scheletro pubblica quel tag con --force, i file che vi aderiscono vengono sovrascritti a ogni aggiornamento di Composer. Non registrare la configurazione o le view che gli utenti modificano.

L’aggiornamento automatico presuppone che l’applicazione contenga lo script, che quell’evento venga eseguito e che il provider registri i percorsi di pubblicazione. Affinché l’aggiornamento sia possibile anche nei deploy che non soddisfano queste condizioni, indica un comando di ripubblicazione che usi il tag specifico del pacchetto.

Allineare le versioni di PHP e degli asset nel deploy

config:cache e view:cache non riscrivono il JavaScript e il CSS pubblicati. Se dopo la pubblicazione li distribuisci con lo stesso URL, il browser o la cache della CDN potrebbero continuare a usare il contenuto precedente. Includi nella procedura di aggiornamento anche la politica di distribuzione dell’applicazione, come URL che riflettono la versione degli artefatti o l’invalidazione della cache. A ogni rilascio verifica le seguenti combinazioni.

In un’applicazione in cui non è ancora stato pubblicato nulla, vengono pubblicati tutti i file compilati necessari.
Con la versione precedente già pubblicata, --force aggiorna i file esistenti e aggiunge quelli nuovi.
L’aggiornamento degli asset non sovrascrive la configurazione, le view o il CSS personalizzato degli utenti.
La gestione dei file eliminati o rinominati è esplicita e non restano riferimenti alla versione precedente.
Il contenuto della nuova versione arriva tramite gli URL di distribuzione reali e PHP collabora correttamente con l’elaborazione lato browser.

Pagine correlate

Struttura interna del package auto-discovery

Verifica le differenze tra l’aggiornamento di Composer, il rilevamento dei provider e la pubblicazione dei file.

Sovrascrivere e aggiornare le view di un pacchetto

Verifica la politica di manutenzione dei template personalizzati dagli utenti.

Cache dei pacchetti e integrazione con optimize

Spiega la cache dei pacchetti, da gestire separatamente dalla pubblicazione dei file.

Gestire la compatibilità tra versioni dei pacchetti

Tratta le modifiche alla destinazione di pubblicazione e al formato di distribuzione come un contratto di compatibilità.

Fonti primarie consultate

Documentazione ufficiale di Laravel: Public assets
Documentazione ufficiale di Laravel: Publishing file groups
Laravel Framework v13.35.0: ServiceProvider — publishes(), addPublishGroup(), pathsToPublish(), pathsForProviderAndGroup().
Laravel Framework v13.35.0: VendorPublishCommand — ambito di selezione, condizioni di sovrascrittura e copia all’interno delle directory.
Scheletro ufficiale delle applicazioni Laravel 13: composer.json — ripubblicazione di laravel-assets tramite post-update-cmd.

Sviluppo con AI

Design pattern

Sviluppo di pacchetti

Struttura dell'applicazione

Novità di Laravel 13

Approfondimento Eloquent

Estensione della validazione

Estensione dell'autenticazione

Sicurezza

Code

Test

Tempo reale

Asset pubblici e aggiornamento di un pacchetto

La pubblicazione non è né una build né una sincronizzazione

I tag non sono namespace riservati al provider

Scegliere le opzioni di ripubblicazione

I file eliminati restano nella destinazione

Aderire a laravel-assets significa accettare un contratto di sovrascrittura

Allineare le versioni di PHP e degli asset nel deploy

Pagine correlate

Struttura interna del package auto-discovery

Sovrascrivere e aggiornare le view di un pacchetto

Cache dei pacchetti e integrazione con optimize

Gestire la compatibilità tra versioni dei pacchetti

Fonti primarie consultate

​La pubblicazione non è né una build né una sincronizzazione

​I tag non sono namespace riservati al provider

​Scegliere le opzioni di ripubblicazione

​I file eliminati restano nella destinazione

​Aderire a laravel-assets significa accettare un contratto di sovrascrittura

​Allineare le versioni di PHP e degli asset nel deploy

​Pagine correlate

Struttura interna del package auto-discovery

Sovrascrivere e aggiornare le view di un pacchetto

Cache dei pacchetti e integrazione con optimize

Gestire la compatibilità tra versioni dei pacchetti

​Fonti primarie consultate

La pubblicazione non è né una build né una sincronizzazione

I tag non sono namespace riservati al provider

Scegliere le opzioni di ripubblicazione

I file eliminati restano nella destinazione

Aderire a laravel-assets significa accettare un contratto di sovrascrittura

Allineare le versioni di PHP e degli asset nel deploy

Pagine correlate

Fonti primarie consultate