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

# Publieke assets van packages publiceren en bijwerken

> Een analyse van de publicatieverwerking in Laravel 13: het distribueren van JavaScript en CSS, het bereik van tags, overschrijfopties en opnieuw publiceren bij Composer-updates, bekeken vanuit langetermijnonderhoud.

Als je de JavaScript of CSS van je package bijwerkt, veranderen de bestanden die al naar de `public`-map van de applicatie zijn gekopieerd niet automatisch. Om te voorkomen dat alleen de PHP-code naar de nieuwe versie gaat terwijl de browser de oude assets blijft gebruiken, moet je vastleggen wie eigenaar is van de publicatiebestemming en hoe updates verlopen.

Deze pagina bouwt voort op [Laravel-packages ontwikkelen](/nl/advanced/package-development) en zet aan de hand van de publicatieverwerking in Laravel 13 het ontwerp van distributie en onderhoud op een rij. Voor de controle van de implementatie is `v13.35.0` van `laravel/framework` gebruikt.

## Publiceren is geen build en geen synchronisatie

`ServiceProvider::publishes()` registreert een bron en een bestemming. Het daadwerkelijke kopiëren van bestanden gebeurt door `vendor:publish`. Het transpileert geen JavaScript, bouwt geen CSS en voegt niets toe aan de Vite-entries van de applicatie.

Als je package al gebouwde bestanden distribueert, kun je bijvoorbeeld de volgende structuur gebruiken.

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

Geef bij de eerste publicatie de provider en de tag expliciet op.

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

In dit voorbeeld worden `public/vendor/courier/courier.css` en `courier.js` aangemaakt. Als je ze als gewone CSS en JavaScript distribueert, kun je ze vanuit Blade als volgt laden.

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

Distribueer je bijvoorbeeld ES-modules, pas dan de manier van laden aan het distributieformaat aan. `asset()` is een helper die een URL genereert; hij bouwt niets, publiceert niets en genereert geen bestandsnamen op basis van de inhoud.

<Warning>
  Plaats in de bron alleen buildartefacten die publiek mogen zijn. De bestemming in dit voorbeeld is `public`, dat via het web toegankelijk is. Neem geen configuratiebestanden of interne data op in dezelfde publicatiegroep.
</Warning>

## Tags zijn geen namespace per provider

`ServiceProvider` registreert publicatiepaden zowel in een array per providerklasse als in een array per tag. De array per tag wordt door meerdere providers gedeeld, dus als je een generieke tag zoals `public` gebruikt, kunnen ook andere packages worden meegenomen.

| Optie | Geselecteerde publicatiepaden |
| - | - |
| `--tag=courier-assets` | De paden van alle providers die deze tag hebben geregistreerd |
| `--provider="Acme\Courier\CourierServiceProvider"` | Alle paden die deze provider heeft geregistreerd |
| Zowel provider als tag | De doorsnede van de paden van die provider en de paden van die tag |
| `--all` | De publicatiepaden van alle providers |

Als je beide opgeeft, gebruikt `pathsForProviderAndGroup()` `array_intersect_key()` **met het bronpad als sleutel**. Het is geen mechanisme om per tag naar een andere bestemming te schakelen. Vermijd een ontwerp waarin je dezelfde bron meerdere keren registreert met een aparte bestemming per doel.

Je kunt `--tag` meerdere keren opgeven. In dat geval wordt elke tag na elkaar gepubliceerd. `--all` keert aan het begin van de selectie al terug, dus ook als je tegelijk `--provider` of `--tag` meegeeft, wordt daar niet op gefilterd.

<Tip>
  Gebruik in je updateprocedure een assettag die specifiek is voor je package, zodat je de configuratie en views van gebruikers niet overschrijft. Als je alleen de provider opgeeft en `--force` toevoegt, kunnen ook de configuratie en views van dezelfde provider worden meegenomen.
</Tip>

## Kies de juiste optie voor opnieuw publiceren

Bij het publiceren van bestanden en mappen bepaalt `VendorPublishCommand` op basis van het bestaan van het doelbestand en de opties of er gekopieerd wordt. De volgende tabel toont het gedrag voor gewone assetbestanden die in de bron bestaan.

| Optie | Bestand bestaat niet op de bestemming | Bestand bestaat al op de bestemming |
| - | - | - |
| Geen | Wordt toegevoegd | Blijft behouden |
| `--force` | Wordt toegevoegd | Wordt overschreven |
| `--existing` | Wordt niet toegevoegd | Wordt overschreven |
| `--existing --force` | Wordt niet toegevoegd | Wordt overschreven |

`--existing` is geen optie die wijzigingen beschermt. Bestaande bestanden worden overschreven, terwijl bestanden die in de nieuwe versie zijn toegevoegd niet worden gepubliceerd. Bij een update waarbij de JavaScript nieuwe bestanden nodig heeft, zijn de artefacten met alleen `--existing` mogelijk niet compleet.

Als de afspraak is dat het package de publicatiebestemming beheert en gebruikers die niet direct bewerken, voer dan na een update het volgende uit.

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

<Warning>
  `--force` voegt geen verschillen samen en overschrijft ook de wijzigingen van gebruikers. Houd CSS die gebruikers aanpassen gescheiden van de artefacten die het package beheert, bijvoorbeeld door die als apart bestand te laden. Hanteer voor het aanpassen van configuratie en views een apart updatebeleid.
</Warning>

### Verwijderde bestanden blijven op de bestemming staan

`moveManagedFiles()` bij het publiceren van mappen doorloopt de bestanden in de bron en schrijft die weg. Er is geen verwerking die bestanden opzoekt en verwijdert die alleen op de bestemming bestaan. Ook `--force` zorgt niet voor een volledige synchronisatie van de map.

Als je bijvoorbeeld in een nieuwe versie `legacy.js` verwijdert, blijft `public/vendor/courier/legacy.js` staan wanneer de oude versie al was gepubliceerd. Ook bij een hernoeming blijft het bestand met de oude naam staan, dus leg in de release notes vast welke bestanden zijn verwijderd of hernoemd en welke verwijzingen zijn gewijzigd.

Als je een procedure aanbiedt om oude bestanden op te ruimen, noem dan concreet de bestanden die het package bezit. Schrijf geen procedure die een hele map verwijdert waarin mogelijk eigen bestanden van gebruikers staan.

## Deelnemen aan laravel-assets betekent instemmen met overschrijven

Het officiële applicatiesjabloon van Laravel 13 bevat in `post-update-cmd` van `composer.json` het volgende script.

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

Dit is een script aan de kant van de applicatie. Het is niet de automatische detectie van packages zelf die de gepubliceerde bestanden bijwerkt. In bestaande applicaties kan het script zijn aangepast of verwijderd, dus controleer de configuratie aan de kant van de gebruiker.

Wil je aan dit updatepad deelnemen, maak dan van het tweede argument van de eerdere `publishes()` een array en registreer dezelfde assets onder twee tags.

```php theme={null}
$this->publishes([
    __DIR__.'/../public' => public_path('vendor/courier'),
], ['courier-assets', 'laravel-assets']);
```

`laravel-assets` is geen tag met een speciale kopieerverwerking. Omdat het script van het sjabloon deze tag met `--force` publiceert, worden de deelnemende bestanden bij Composer-updates overschreven. Registreer hier geen configuratie of views die gebruikers bewerken.

<Info>
  Automatische updates veronderstellen dat de applicatie het script bevat, dat de bijbehorende gebeurtenis wordt uitgevoerd en dat de provider de publicatiepaden registreert. Geef ook een command voor opnieuw publiceren met de packagespecifieke tag, zodat updates ook mogelijk zijn bij deployments die niet aan deze voorwaarden voldoen.
</Info>

## Houd PHP en assets bij de deployment op dezelfde versie

```mermaid theme={null}
flowchart TD
    A["Package bijwerken"] --> B["Publicatiepaden registreren"]
    B --> C["vendor:publish --force met eigen tag<br>of het updatescript van laravel-assets"]
    C --> D["Nieuwe bestanden toevoegen<br>Bestaande bestanden overschrijven"]
    D --> E["Aangegeven oude bestanden opruimen<br>Cachebeleid voor browser en CDN toepassen"]
    E --> F["Controleren dat PHP en assets met dezelfde versie werken"]
```

`config:cache` en `view:cache` herschrijven gepubliceerde JavaScript en CSS niet. Als je na publicatie via dezelfde URL blijft serveren, kan door caching in de browser of het CDN oude inhoud worden gebruikt. Neem ook het distributiebeleid van de applicatie op in de updateprocedure, zoals URL's die de versie van de artefacten weerspiegelen of het ongeldig maken van caches.

Controleer bij elke release de volgende combinaties.

* In een applicatie zonder eerdere publicatie worden alle benodigde gebouwde bestanden gepubliceerd.
* Als de oude versie al is gepubliceerd, worden bestaande bestanden met `--force` bijgewerkt en nieuwe bestanden toegevoegd.
* Assetupdates overschrijven de configuratie, views en eigen CSS van gebruikers niet.
* De afhandeling van verwijderde of hernoemde bestanden is expliciet vastgelegd en er blijven geen verwijzingen naar de oude versie over.
* Via de daadwerkelijke URL's komt de inhoud van de nieuwe versie aan en werken PHP en de verwerking in de browser samen.

## Gerelateerde pagina's

<Columns cols={2}>
  <Card title="De interne structuur van package discovery" icon="magnifying-glass" href="/nl/advanced/package-discovery">
    Bekijk de verschillen tussen Composer-updates, het detecteren van providers en het publiceren van bestanden.
  </Card>

  <Card title="Views van packages overschrijven en bijwerken" icon="eye" href="/nl/advanced/package-views">
    Bekijk het onderhoudsbeleid voor templates die gebruikers aanpassen.
  </Card>

  <Card title="Packagecaches integreren in optimize" icon="gears" href="/nl/advanced/package-optimization">
    Uitleg over packagecaches die je los van het publiceren van bestanden beheert.
  </Card>

  <Card title="Versiecompatibiliteit van packages beheren" icon="code-branch" href="/nl/advanced/package-versioning">
    Behandel wijzigingen in publicatiebestemmingen en distributieformaten als onderdeel van je compatibiliteitsafspraken.
  </Card>
</Columns>

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: Public assets](https://github.com/laravel/docs/blob/13.x/packages.md#public-assets)
* [Officiële Laravel-documentatie: 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) — selectiebereik, voorwaarden voor overschrijven en het kopiëren binnen mappen.
* [Officieel Laravel 13-applicatiesjabloon: composer.json](https://github.com/laravel/laravel/blob/13.x/composer.json) — opnieuw publiceren van `laravel-assets` via `post-update-cmd`.


## Related topics

- [Laravel-packages ontwikkelen](/nl/advanced/package-development.md)
- [Geavanceerde onderwerpen](/nl/advanced/index.md)
- [Migrations van packages publiceren en bijwerken](/nl/advanced/package-migrations.md)
- [Views van packages overschrijven en bijwerken](/nl/advanced/package-views.md)
- [Laravel Boost](/nl/boost.md)


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