panel:assets

Melaporkan kondisi published frontend assets PandaBear:

• file mana yang tertinggal dari versi package;
• file mana yang sudah diedit oleh application;
• file mana yang berubah di kedua sisi;
• dan file mana yang aman untuk diperbarui otomatis.

Jalankan setelah setiap:

composer update

yang memperbarui package PandaBear.

php artisan panel:assets

Contoh report:

  out of date ........................................................ 12
  yours ............................................................... 3
  current ........................................................... 284

INFO  Run `php artisan panel:assets --update` to write the safe ones.

Untuk menulis update yang aman:

php artisan panel:assets --update

  resources/js/panel/tables/DataTable.vue ....................... written
  …
INFO  Wrote 12 file(s). Run `npm run build`.

Masalah yang Diselesaikan Command Ini

Frontend PandaBear dipublish ke application, bukan diimport langsung dari package.

Pendekatan ini dipilih karena:

• component registry menggunakan build-time import.meta.glob allowlist terhadap source tree application;
• frontend source dapat dibaca dan didebug oleh developer;
• application dapat mengubah component yang dipublish.

Konsekuensinya, setelah file dipublish application menjadi pemilik copy tersebut. Package update tidak dapat begitu saja mengganti semua file.

vendor:publish saja tidak cukup untuk upgrade:

• tanpa --force, semua existing file dilewati sehingga tidak ada update;
• dengan --force, semua file ditimpa termasuk custom edit application.

Kedua mode tidak dapat membedakan:

file stale

dengan:

file sengaja diedit application

Karena keduanya sama-sama "berbeda dari package copy saat ini".

.panel-assets.json

File:

.panel-assets.json

mencatat hash setiap file pada saat file tersebut dipublish.

Dengan adanya nilai ketiga ini, perbandingan menjadi three-way:

published baseline
vs
application current
vs
package current

Prinsipnya serupa dengan common ancestor pada merge.

Signature

panel:assets
    {--update : Write the files that are safe to write}
    {--force : Also overwrite files this application has edited}

Option	Default	Efek
tanpa option	—	Report only; tidak menulis file.
--update	off	Menulis file dengan status new dan out of date.
--force	off	Mengaktifkan penulisan dan juga menimpa CONFLICT serta yours.

php artisan panel:assets
php artisan panel:assets --update
php artisan panel:assets --force

Tujuh Status Asset

Status	Label report	Disk vs baseline	Package vs baseline	--update	--force
AssetManifest::NEW	new	belum tercatat	package mengirim file	tulis	tulis
AssetManifest::STALE	out of date	sama	berbeda	tulis	tulis
AssetManifest::CONFLICT	CONFLICT	berbeda	berbeda	tidak	tulis
AssetManifest::MODIFIED	yours	berbeda	sama	tidak	tulis
AssetManifest::DELETED	deleted by you	tidak ada	masih dikirim package	tidak	tidak
AssetManifest::REMOVED_UPSTREAM	no longer shipped	tercatat	tidak lagi dikirim	tidak	tidak
AssetManifest::CURRENT	current	sama	sama	tidak	tidak

Hanya dua status yang ditulis otomatis oleh --update:

NEW
STALE

Pada keduanya dapat dibuktikan bahwa application belum memiliki edit yang perlu dipertahankan.

--force sengaja tidak menghidupkan kembali:

deleted by you
no longer shipped

File yang Anda hapus sengaja tetap hilang. File yang sudah tidak dikirim package juga tidak dibangkitkan kembali.

Conflict

Contoh:

WARN  2 file(s) changed both here and upstream. Neither copy is safe to throw away, so
      nothing was written. Diff each against the package copy under
      vendor/chocoalano/panel, then re-run with --force once you have merged:

  resources/js/panel/tables/DataTable.vue
  resources/js/panel/forms/registry.ts

Framework tidak mencoba menebak merge karena itu dapat menghapus perubahan application.

Lakukan diff manual:

diff -u vendor/chocoalano/panel/resources/js/panel/tables/DataTable.vue \
        resources/js/panel/tables/DataTable.vue

Merge perubahan upstream ke copy application.

Setelah itu Anda dapat:

• mempertahankan hasil merge; file akan dibaca sebagai yours/MODIFIED;
• atau mengambil package copy menggunakan --force jika custom edit tidak lagi diperlukan.

Hanya conflict yang dicetak per path. File current biasanya jumlahnya sangat besar dan menampilkan semuanya justru membuat report sulit dibaca.

Isi .panel-assets.json

Contoh:

{
    "_": "Written by php artisan panel:install / panel:assets. Commit this file: it is the record of which version of the panel frontend this application published, and without it an upgrade cannot tell your edits from a stale copy.",
    "files": {
        "resources/js/panel/components/PanelSidebar.vue": "…",
        "resources/js/panel/icons/registry.ts": "…"
    }
}

File berada di root application dan seharusnya di-commit seperti composer.lock.

Jangan menaruhnya di bootstrap/cache atau storage, karena manifest ini bukan disposable runtime cache. Ini adalah catatan baseline yang dibutuhkan untuk upgrade berikutnya.

Hash dihitung dari application copy, dengan line ending:

\r\n

dinormalisasi ke:

\n

agar Windows checkout tidak membuat semua file terlihat berubah.

Jika manifest tidak tersedia:

WARN  No .panel-assets.json, so there is no record of what this application published.
      Everything already identical to the package reads as current; anything else reads
      as new. Run --update to write one.

Manifest pertama ditulis oleh panel:install, lalu diperbarui setelah run yang benar-benar menulis file.

Manifest direbuild dari kondisi file di disk, bukan dari intent command, sehingga selalu mencatat keadaan actual application.

API

PandaPanel\Support\Installer\AssetManifest:

Method	Signature
path	static path(): string — base_path('.panel-assets.json')
exists	static exists(): bool
read	static read(): array<string, string>
write	static write(array $existing = []): void
compare	static compare(?array $files = null): array<string, array{status: string, destination: string, source: string|null}>

Contoh:

use PandaPanel\Support\Installer\AssetManifest;

foreach (AssetManifest::compare() as $relative => $entry) {
    if ($entry['status'] === AssetManifest::CONFLICT) {
        echo $relative.PHP_EOL;
    }
}

File list berasal dari:

PandaPanel\Support\Installer\PublishedAssets

Service provider publishes() dan panel:assets membaca source list yang sama agar tidak terjadi drift.

API:

Method	Signature
map	static map(): array<string, string> — source directory => destination
files	static files(): array<string, string> — absolute destination => absolute source, per file
relative	static relative(string $path): string

Asset yang Dipublish

Package path	Application path
resources/js/panel	FrontendPaths::panel(), default resources/js/panel
resources/js/components	resources/js/components
resources/js/composables	resources/js/composables
resources/js/lib	resources/js/lib
resources/js/pages	resources/js/pages
resources/js/types	resources/js/types
resources/css/panda-panel.css	resources/css/panda-panel.css

Exit Code

Selalu:

0

termasuk ketika conflict ditemukan.

Conflict berarti command berhasil melakukan analisis dan menemukan sesuatu yang perlu di-review manusia; itu bukan runtime failure.

Jika CI Anda ingin gagal ketika ada conflict, gunakan AssetManifest::compare() pada custom script.

Hal yang Perlu Diperhatikan

• Tanpa --update atau --force, command hanya report.
• Jalankan npm run build setelah asset berubah. File yang ditulis adalah Vue/TypeScript source.
• --force menimpa custom edit tanpa backup. Commit dulu.
• File yang Anda hapus tetap dihapus.
• Commit .panel-assets.json. Tanpanya upgrade berikutnya tidak bisa membedakan edit application dan stale copy.
• vendor:publish --force bukan tool upgrade setelah install pertama.
• Menghapus manifest dapat dipulihkan tetapi kehilangan baseline. File yang berbeda akan terlihat seperti new, sehingga --update berikutnya berpotensi menimpa custom edit.

Lihat Juga

• panel:install
• Publish tags
• Frontend assets
• Assets
• Updating assets
• The asset manifest
• Asset conflicts
• Asset conflicts troubleshooting
• Upgrade guide
• Frontend build
• Frontend paths