Publieke assets van packages publiceren en bijwerken

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

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

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

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.

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

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.

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.

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.

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.

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

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

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.

{
    "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.

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

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.

Houd PHP en assets bij de deployment op dezelfde versie

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

De interne structuur van package discovery

Bekijk de verschillen tussen Composer-updates, het detecteren van providers en het publiceren van bestanden.

Views van packages overschrijven en bijwerken

Bekijk het onderhoudsbeleid voor templates die gebruikers aanpassen.

Packagecaches integreren in optimize

Uitleg over packagecaches die je los van het publiceren van bestanden beheert.

Versiecompatibiliteit van packages beheren

Behandel wijzigingen in publicatiebestemmingen en distributieformaten als onderdeel van je compatibiliteitsafspraken.

Geraadpleegde primaire bronnen

Officiële Laravel-documentatie: Public assets
Officiële Laravel-documentatie: Publishing file groups
Laravel Framework v13.35.0: ServiceProvider — publishes(), addPublishGroup(), pathsToPublish(), pathsForProviderAndGroup().
Laravel Framework v13.35.0: VendorPublishCommand — selectiebereik, voorwaarden voor overschrijven en het kopiëren binnen mappen.
Officieel Laravel 13-applicatiesjabloon: composer.json — opnieuw publiceren van laravel-assets via post-update-cmd.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Publieke assets van packages publiceren en bijwerken

Publiceren is geen build en geen synchronisatie

Tags zijn geen namespace per provider

Kies de juiste optie voor opnieuw publiceren

Verwijderde bestanden blijven op de bestemming staan

Deelnemen aan laravel-assets betekent instemmen met overschrijven

Houd PHP en assets bij de deployment op dezelfde versie

Gerelateerde pagina’s

De interne structuur van package discovery

Views van packages overschrijven en bijwerken

Packagecaches integreren in optimize

Versiecompatibiliteit van packages beheren

Geraadpleegde primaire bronnen

​Publiceren is geen build en geen synchronisatie

​Tags zijn geen namespace per provider

​Kies de juiste optie voor opnieuw publiceren

​Verwijderde bestanden blijven op de bestemming staan

​Deelnemen aan laravel-assets betekent instemmen met overschrijven

​Houd PHP en assets bij de deployment op dezelfde versie

​Gerelateerde pagina’s

De interne structuur van package discovery

Views van packages overschrijven en bijwerken

Packagecaches integreren in optimize

Versiecompatibiliteit van packages beheren

​Geraadpleegde primaire bronnen

Publiceren is geen build en geen synchronisatie

Tags zijn geen namespace per provider

Kies de juiste optie voor opnieuw publiceren

Verwijderde bestanden blijven op de bestemming staan

Deelnemen aan laravel-assets betekent instemmen met overschrijven

Houd PHP en assets bij de deployment op dezelfde versie

Gerelateerde pagina’s

Geraadpleegde primaire bronnen