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

# Asset pubblici e aggiornamento di un pacchetto

> Analizza il processo di pubblicazione di Laravel 13 e scopri, in un'ottica di manutenzione a lungo termine, la distribuzione di JavaScript e CSS, l'ambito di selezione dei tag, le opzioni di sovrascrittura e la ripubblicazione durante gli aggiornamenti di Composer.

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

```text theme={null}
courier/
├── public/
│   ├── courier.css
│   └── courier.js
└── src/
    └── CourierServiceProvider.php
```

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

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

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

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

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

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

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

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

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

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

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

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

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

## Allineare le versioni di PHP e degli asset nel deploy

```mermaid theme={null}
flowchart TD
    A["Aggiornare il pacchetto"] --> B["Registrare i percorsi di pubblicazione"]
    B --> C["vendor:publish --force con il tag specifico<br>oppure script di aggiornamento laravel-assets"]
    C --> D["Aggiungere i nuovi file<br>Sovrascrivere i file esistenti"]
    D --> E["Ripulire i vecchi file indicati<br>Applicare la politica di cache di browser e CDN"]
    E --> F["Verificare che PHP e asset funzionino con la stessa versione"]
```

`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

<Columns cols={2}>
  <Card title="Struttura interna del package auto-discovery" icon="magnifying-glass" href="/it/advanced/package-discovery">
    Verifica le differenze tra l'aggiornamento di Composer, il rilevamento dei provider e la pubblicazione dei file.
  </Card>

  <Card title="Sovrascrivere e aggiornare le view di un pacchetto" icon="eye" href="/it/advanced/package-views">
    Verifica la politica di manutenzione dei template personalizzati dagli utenti.
  </Card>

  <Card title="Cache dei pacchetti e integrazione con optimize" icon="gears" href="/it/advanced/package-optimization">
    Spiega la cache dei pacchetti, da gestire separatamente dalla pubblicazione dei file.
  </Card>

  <Card title="Gestire la compatibilità tra versioni dei pacchetti" icon="code-branch" href="/it/advanced/package-versioning">
    Tratta le modifiche alla destinazione di pubblicazione e al formato di distribuzione come un contratto di compatibilità.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: Public assets](https://github.com/laravel/docs/blob/13.x/packages.md#public-assets)
* [Documentazione ufficiale di Laravel: Publishing file groups](https://github.com/laravel/docs/blob/13.x/packages.md#publishing-file-groups)
* [Laravel Framework v13.35.0: ServiceProvider](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Support/ServiceProvider.php) — `publishes()`, `addPublishGroup()`, `pathsToPublish()`, `pathsForProviderAndGroup()`.
* [Laravel Framework v13.35.0: VendorPublishCommand](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/VendorPublishCommand.php) — ambito di selezione, condizioni di sovrascrittura e copia all'interno delle directory.
* [Scheletro ufficiale delle applicazioni Laravel 13: composer.json](https://github.com/laravel/laravel/blob/13.x/composer.json) — ripubblicazione di `laravel-assets` tramite `post-update-cmd`.


## 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)
- [Laravel Package Skeleton — template starter per pacchetti ufficiali](/it/blog/package-skeleton-introduction.md)
- [Registrazione e cache delle route di un pacchetto](/it/advanced/package-routes.md)


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