v13.34.0 を参照しています。
登録と公開は別の処理
loadViewsFrom() は名前空間に検索パスを登録します。publishes() はコピー元とコピー先を登録し、実際のコピーは vendor:publish が行います。次の例では、公開しなくても courier::deliveries.show を利用できます。
src/CourierServiceProvider.php
resources/views/deliveries/show.blade.php に置きます。ビュー名のドットは、検索時にディレクトリ区切りへ変換されます。
resources/views/deliveries/show.blade.php
loadViewsFrom() の第2引数に指定した courier が、ビュー参照と上書き先ディレクトリの契約になります。
ファイル単位で上書き先を探す
ServiceProvider::loadViewsFrom() は view が解決されたときに、設定の view.paths を順番に確認します。各パスに vendor/courier ディレクトリが存在する場合は、そのディレクトリを名前空間へ追加し、最後にパッケージ側のパスを追加します。
FileViewFinder は、その名前空間のパスを順番に検索し、最初に見つかったファイルを返します。標準の resources/views を使う構成では、次の順序です。
これはディレクトリ全体の切り替えではありません。利用者が deliveries/show.blade.php だけを上書きしても、上書きしていない他のビューはパッケージ側から読み込まれます。
view.paths が複数ある構成では、上書き先も複数になり得ます。resource_path('views/vendor/courier') はこの例の公開先であり、検索対象をそこだけに固定する処理ではありません。名前空間はパッケージ固有のものにし、複数のプロバイダーで同じ名前へパスを追加する設計を避けてください。必要なビューだけをカスタマイズする
利用者は次のコマンドでテンプレートをコピーできます。プロバイダーとタグを指定し、他のリソースを巻き込まないようにします。再公開では差分のマージをしない
VendorPublishCommand は通常、同名の公開先ファイルが存在する場合にコピーをスキップします。--force は既存ファイルを上書きします。また、--existing も「公開済みのファイルを上書きする」オプションであり、利用者の編集を保持するモードではありません。
どの方法も、旧版・新版・利用者の編集を比較したマージではありません。パッケージから削除されたビューを公開先から自動で取り除く処理でもありません。更新手順を「同じタグを再公開するだけ」にしないでください。
ビューも公開APIとして保守する
ビュー名だけでなく、受け取るデータや参照する部品も利用者のカスタマイズに影響します。たとえば、新版でtrackingCode を別の変数名へ変更すると、旧テンプレートを残している利用者は新しいコードから必要な値を受け取れなくなります。
リリース前に、次の契約を確認します。
- 名前空間と
deliveries.showなどのビュー名を不用意に変更しない。 - 渡す変数、型、必須・任意の区別を記録する。
@includeや@extendsの参照先、Bladeコンポーネントのpropsも変更点に含める。- 修正したビューと、公開済みの旧版へ適用すべき変更をリリースノートに記載する。
Bladeキャッシュは上書きファイルを更新しない
view:cache はBladeテンプレートをPHPへ事前コンパイルします。ViewCacheCommand は最初に view:clear を実行し、通常のビューパスと名前空間に登録されたパスを集めてコンパイル対象を探します。
検索結果のキャッシュとは区別する
FileViewFinder::find() は、見つけたパスをそのFinderインスタンスの $views 配列へ保存します。また、上書きディレクトリの存在確認は loadViewsFrom() のコールバックで行われます。起動後に新しいディレクトリを追加しても、すでに登録済みの検索パスへ自動追加されるわけではありません。
view:clear は、別の実行中プロセスが保持するFinderの状態を一括で消すコマンドではありません。Octaneなどの長時間動くプロセスでは、通常のデプロイ手順に従い再読み込みしてください。Finderの flush() は検索結果を消しますが、新しい上書きディレクトリの登録まで行う処理ではありません。
リリース前に確認すること
パッケージのテストに加え、利用アプリケーションで次の組み合わせを確認します。最新テンプレートだけを描画するテストでは、旧版を公開済みの利用者への互換性は検証できません。- 未公開の状態で、パッケージのビューが描画される。
- 1つだけ上書きすると、そのファイルだけが優先され、他はパッケージへフォールバックする。
- 旧版の公開済みテンプレートを残した状態でも、新版が渡すデータで描画できる。
- 通常の再公開でカスタマイズが保持され、未公開ファイルの追加も意図どおりである。
- 上書きファイルの変更後に
view:cacheが成功し、新しい起動で変更後の表示になる。
関連ページ
ビュー
ビューの作成、データの受け渡し、事前コンパイルの基本を確認します。
Bladeテンプレート
レイアウト、include、コンポーネントの使い方を確認します。
バージョン互換性管理
テンプレートの契約変更をリリース方針に結び付けます。
Octane
長時間動くアプリケーションのライフサイクルと再読み込みを確認します。