public にコピー済みのファイルは自動では変わりません。PHPコードだけが新版になり、ブラウザーが旧版のアセットを使い続ける状態を防ぐには、公開先の所有者と更新手順を決める必要があります。
このページではパッケージ開発の基礎を前提に、Laravel 13の公開処理から配布と保守の設計を整理します。実装の確認には laravel/framework の v13.35.0 を使用しています。
公開はビルドでも同期でもない
ServiceProvider::publishes() はコピー元とコピー先を登録します。実際にファイルをコピーするのは vendor:publish です。JavaScriptのトランスパイルやCSSのビルド、アプリケーションのViteエントリへの追加は行いません。
パッケージ側でビルド済みのファイルを配布する場合、たとえば次の構成にします。
public/vendor/courier/courier.css と courier.js が作られます。通常のCSSとJavaScriptとして配布する設計なら、Bladeから次のように参照できます。
asset() はURLを生成するヘルパーであり、ビルドや公開、内容に応じたファイル名の生成をするものではありません。
タグはプロバイダー専用の名前空間ではない
ServiceProvider は公開パスをプロバイダークラス別の配列と、タグ別の配列に登録します。タグ別の配列は複数のプロバイダーで共有されるため、public のような汎用タグを使うと他のパッケージも対象になり得ます。
両方を指定したとき、
pathsForProviderAndGroup() はコピー元パスをキーとして array_intersect_key() を使います。タグによって別のコピー先へ切り替える仕組みではありません。同じコピー元を何度も登録して用途別のコピー先を持たせる設計は避けてください。
--tag は繰り返し指定できます。その場合は各タグを順に公開します。--all は選択処理の冒頭で戻るため、--provider や --tag を同時に付けても絞り込みには使われません。
再公開オプションを使い分ける
VendorPublishCommand のファイル公開とディレクトリ公開は、コピー先ファイルの存在とオプションを使ってコピーを判断します。次の表は、コピー元に存在する通常のアセットファイルについての動作です。
--existing は編集を保護するオプションではありません。既存ファイルを上書きする一方、新版で追加されたファイルは公開しません。JavaScriptが新しい追加ファイルを必要とする更新では、--existing だけでは成果物がそろわない可能性があります。
パッケージが公開先を管理し、利用者が直接編集しない契約なら、更新後に次を実行します。
削除したファイルは公開先に残る
ディレクトリ公開のmoveManagedFiles() は、コピー元にあるファイルを走査して書き込みます。公開先にしかないファイルを探して削除する処理はありません。--force もディレクトリの完全同期にはなりません。
たとえば新版で legacy.js を削除しても、旧版を公開済みなら public/vendor/courier/legacy.js は残ります。改名した場合も旧名のファイルは残るため、リリースノートには削除・改名したファイルと参照先の変更を記録します。
旧ファイルを除去する手順を提供する場合は、パッケージが所有するファイルを具体的に示してください。利用者の独自ファイルが置かれている可能性のあるディレクトリを丸ごと削除する手順にはしません。
laravel-assetsへの参加は上書き契約を意味する
Laravel 13の公式アプリケーション雛形には、composer.json の post-update-cmd に次のスクリプトがあります。
publishes() の第2引数を配列に変更して、同じアセットを2つのタグへ登録します。
laravel-assets は特別なコピー処理を持つタグではありません。雛形のスクリプトがそのタグを --force 付きで公開するため、参加したファイルはComposer更新時の上書き対象になります。利用者が編集する設定やビューは登録しないでください。
自動更新の前提は、アプリケーション側にスクリプトがあり、そのイベントが実行され、プロバイダーが公開パスを登録していることです。この前提を満たさないデプロイでも更新できるよう、パッケージ固有のタグを使った再公開コマンドを案内します。
デプロイでPHPとアセットの版をそろえる
config:cache や view:cache は公開済みのJavaScript・CSSを書き換えません。公開後も同じURLで配信する設計なら、ブラウザーやCDNのキャッシュによって古い内容が使われることがあります。配布物のバージョンを反映したURLやキャッシュ無効化など、アプリケーションの配信方針も更新手順に含めます。
リリースごとに次の組み合わせを確認します。
- 未公開のアプリケーションで、必要なビルド済みファイルがすべて公開される。
- 旧版を公開済みの状態で、
--forceによって既存ファイルが更新され、新しいファイルが追加される。 - アセット更新が利用者の設定・ビュー・独自CSSを上書きしない。
- 削除・改名したファイルの扱いが明示され、旧版の参照が残っていない。
- 実際の配信URLで新版の内容が届き、PHPとブラウザー側の処理が連携する。
関連ページ
パッケージ自動検出
Composerの更新、プロバイダーの検出、ファイル公開の違いを確認します。
パッケージビューの上書きと更新
利用者がカスタマイズするテンプレートの保守方針を確認します。
パッケージのキャッシュとoptimizeへの統合
ファイル公開とは別に管理するパッケージキャッシュを解説します。
バージョン互換性管理
公開先や配布形式の変更を互換性の契約として扱います。
参照した一次情報
- Laravel公式ドキュメント: Public assets
- Laravel公式ドキュメント: Publishing file groups
- Laravel Framework v13.35.0: ServiceProvider —
publishes()、addPublishGroup()、pathsToPublish()、pathsForProviderAndGroup()。 - Laravel Framework v13.35.0: VendorPublishCommand — 選択範囲、上書き条件、ディレクトリ内のコピー処理。
- Laravel 13公式アプリケーション雛形: composer.json —
post-update-cmdによるlaravel-assetsの再公開。