Panduan Upgrade

Panduan ini menjelaskan prosedur memindahkan aplikasi yang sudah terinstal ke release chocoalano/panel yang lebih baru, dalam urutan yang memang harus dijalankan. Gunakan panduan ini setiap kali composer update memindahkan version package ini. Daftar perubahan yang benar-benar mematahkan compatibility beserta perbaikan terkecilnya tersedia di Breaking changes.

Contoh minimal yang dapat langsung digunakan

composer update chocoalano/panel

php artisan panel:assets            # read the report first
php artisan panel:assets --update   # write only the files you have never edited
php artisan panel:icons             # the icon registry is a published file
npm run build

php artisan migrate
php artisan optimize:clear
php artisan test

Pada aplikasi yang belum pernah mengedit published file, rangkaian di atas adalah seluruh proses upgrade. Bagian berikutnya menjelaskan apa yang harus dilakukan ketika aplikasi memiliki kustomisasi atau state tambahan.

Apa saja yang benar-benar berubah saat upgrade

Ada lima jenis state yang bergerak, dan hanya yang pertama dipindahkan langsung oleh Composer:

Yang berubah	Dipindahkan oleh	Dibiarkan oleh composer update
vendor/chocoalano/panel	composer update	—
resources/js/**, resources/css/panda-panel.css	panel:assets --update	ya — file tersebut sudah menjadi milik aplikasi
config/panda-panel.php	tidak ada, kecuali Anda publish ulang	ya — config key baru tetap mendapat default, lihat bagian terkait
Database table	php artisan migrate	ya
bootstrap/cache/panels.php, config cache, route cache	optimize:clear, atau panel:clear	ya

Tiga item di tengah inilah yang membuat upgrade menjadi sebuah prosedur, bukan hanya satu command.

1. Update package

composer update chocoalano/panel

Atau update seluruh dependency tree jika Anda sekaligus meng-upgrade Laravel:

composer update

composer update chocoalano/panel tetap mengikuti constraint pada composer.json. Jika constraint Anda ^0.1, Composer tidak akan masuk ke 0.2, dan itu memang benar karena minor release pada seri 0.x diperbolehkan breaking. Untuk melewati boundary tersebut dengan sengaja:

composer require chocoalano/panel:^0.2

Baca Breaking changes sebelum melakukannya, dan Versioning untuk memahami apa yang dijanjikan version number.

Jika Composer menolak resolve, why-not menunjukkan constraint yang menghalangi:

composer why-not chocoalano/panel ^0.2

2. Sinkronkan published frontend

Komponen Vue panel disalin ke aplikasi pada saat instalasi. Ini membuat source dapat dibaca dan di-debug serta dibutuhkan oleh build-time component registry. Konsekuensinya, composer update tidak dapat memperbarui file yang sekarang sudah menjadi milik aplikasi.

php artisan panel:assets

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

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

php artisan panel:assets --update

--update hanya menulis dua kategori: file yang belum pernah dimiliki aplikasi dan file yang belum pernah diedit. File yang Anda ubah dibiarkan. File yang berubah di kedua sisi hanya dilaporkan lengkap dengan path dan tidak pernah ditulis otomatis — lihat Menyelesaikan konflik asset, yaitu satu-satunya bagian dari upgrade yang memang tidak seharusnya diputuskan tool secara otomatis.

Command	Yang ditulis
php artisan panel:assets	tidak ada; hanya report
php artisan panel:assets --update	new dan out of date
php artisan panel:assets --force	kategori di atas, ditambah yours dan CONFLICT, semuanya ditimpa

Jika aplikasi berasal dari version sebelum .panel-assets.json tersedia, belum ada baseline untuk dibandingkan. Command akan menjelaskan kondisi tersebut lalu tetap berjalan: file yang sudah identik dengan package dibaca current, sedangkan file yang benar-benar berbeda akan dilaporkan. Jalankan --update sekali untuk membuat manifest lalu commit file tersebut. Jika semua file sudah identik, --update tidak menulis apa pun dan manifest tidak terbentuk; buat manifest melalui pemeriksaan installer:

php artisan panel:install --no-panel --no-user --no-interaction

Command tersebut mempublikasikan asset, selalu menulis .panel-assets.json, dan memeriksa kembali boundary frontend — npm dependencies, host modules, Vite, Inertia, dan layout rule — tanpa membuat panel baru maupun meminta pembuatan user.

3. Bangun ulang icon registry

php artisan panel:icons
php artisan panel:icons --check   # for CI: fail instead of writing

resources/js/panel/icons/registry.ts adalah published file yang dihasilkan ulang berdasarkan icon yang dideklarasikan panel. Release baru yang menambahkan built-in action dapat menambahkan icon baru. Jalankan command ini setelah panel:assets, karena --force dapat menimpa registry hasil generate dengan salinan milik package.

Icon yang tidak tercatat di registry akan menampilkan satu warning pada development. Di production icon hanya tidak terlihat, karena ini merupakan build problem, bukan runtime problem.

4. Build ulang frontend

npm install     # only when the compatibility table moved
npm run build

Langkah ini wajib. Setiap component registry adalah import.meta.glob yang dievaluasi pada saat build. File yang sudah berubah di disk belum masuk bundle sampai build dijalankan. Panel yang terlihat tidak berubah setelah upgrade sering kali sebenarnya hanya belum dibuild ulang.

Periksa npm range terhadap Compatibility jika release mengubah requirement. panel:install membaca package.json milik package dan melaporkan dependency yang belum dideklarasikan aplikasi.

5. Jalankan migration

php artisan migrate

Secara default migration package dijalankan langsung dari package karena load_migrations adalah true. Release yang menambahkan table otomatis membuat migration tersebut ikut dijalankan oleh php artisan migrate tanpa memerlukan publish step:

Migration	Table
create_notifications_table	notifications
add_email_two_factor_to_users_table	users.two_factor_email_confirmed_at
create_panel_integrations_table	panel_integrations, panel_integration_deliveries
add_history_and_signing_to_panel_integrations	history dan signing columns

Setiap migration memeriksa kondisi sebelum mengubah schema, sehingga aplikasi yang sudah memiliki table notifications tidak kehilangan ownership atas table tersebut.

Jika migration pernah dipublish ke database/migrations saat instalasi, file tersebut sudah menjadi milik aplikasi. Set load_migrations ke false agar schema yang sama tidak diterapkan dua kali, lalu publish ulang hanya jika ingin mengambil migration baru:

php artisan vendor:publish --tag=panda-panel-migrations

// config/panda-panel.php
'load_migrations' => false,

6. Bersihkan cache

php artisan optimize:clear

Panel manifest diregistrasikan bersama config dan route cache sehingga optimize dan optimize:clear sudah mencakupnya:

// PandaPanel\PandaPanelServiceProvider

$this->optimizes(optimize: 'panel:cache', clear: 'panel:clear', key: 'panels');

Command	Efek
php artisan panel:cache	Melakukan discovery resource, page, dan widget satu kali lalu menulis bootstrap/cache/panels.php
php artisan panel:clear	Menghapus manifest agar discovery berjalan kembali
php artisan optimize	Menjalankan panel:cache bersama cache framework lainnya
php artisan optimize:clear	Menjalankan panel:clear bersama cache lainnya

Manifest stale adalah failure mode yang penting: ketika manifest tersedia, discovery tidak dijalankan lagi. Resource yang ditambahkan setelah manifest dibuat bisa benar-benar tidak masuk panel — tidak ada route, navigation entry, maupun error. Di luar production, manifest menyimpan fingerprint discovery path dan boot akan membandingkannya sehingga state stale dapat diperingatkan. Di production manifest menjadi authority dan filesystem tidak discan. Deployment yang menambahkan resource harus membangun ulang panel:cache.

7. Verifikasi

php artisan panel:plugins   # every plugin still registers, at which version
php artisan panel:assets    # should now read: current, plus anything you own
php artisan test

Jalankan panel:plugins lebih awal karena plugin dengan constraint requiresPanel yang tidak cocok terhadap version baru akan melempar exception saat boot. Itu berarti seluruh Artisan command dapat gagal, termasuk panel:plugins, tetapi exception yang muncul menyebut plugin dan constraint yang perlu diperbaiki. Failure ini disengaja karena lebih aman daripada membiarkan plugin incompatible tetap berjalan.

Setelah itu buka URL panel dan periksa tiga hal yang hanya dapat divalidasi browser: sidebar menampilkan resource yang diharapkan, icon berhasil dirender, dan browser console bersih.

Catatan khusus per version

Belum dirilis

Tujuh perubahan membutuhkan penyesuaian, dan dua di antaranya bersifat silent — code tetap berjalan tetapi melakukan hal yang salah. Penjelasan lengkap beserta fix tersedia di Breaking changes:

#	Perubahan	Silent
1	Upload diotorisasi berdasarkan form tempatnya berada, bukan berdasarkan viewAny	ya
2	Migration down() tidak lagi menghapus table notifications yang tidak dibuat package	ya
3	PanelPlugin::publishes() dipindahkan ke contract	tidak — fatal saat registration
4	Guest redirect diregistrasikan oleh service provider	tidak
4a	/dashboard me-redirect user yang sudah login masuk ke panel	tidak
4b	Sembilan kesalahan schema sekarang melempar PanelSchemaException	tidak — exception saat schema build
5	Testing helper dipindahkan ke package	tidak
6	Password::toPasswordRulesString() tidak lagi dipanggil langsung	tidak
7	panel:install mendaftarkan panel dan menawarkan pembuatan user	tidak

Dua item sebaiknya diperiksa sebelum upgrade:

# 1. If you published the frontend before the upload change, this file must be updated.
php artisan panel:assets | grep uploadEndpoint

# 4b. Schema refusals surface at schema-build time, which the suite reaches.
php artisan test

Upgrade di deploy pipeline

panel:assets --update menulis source file, sehingga command ini seharusnya dijalankan saat development dan hasilnya di-commit, bukan dijalankan langsung pada deployment. Deployment yang menjalankannya akan mengubah file di build yang kemungkinan dibuang pada deploy berikutnya, dan compiled bundle juga belum tentu menyertakan perubahannya.

Untuk deploy aplikasi yang sudah di-upgrade dan committed:

composer install --no-dev --optimize-autoloader
php artisan migrate --force
npm ci && npm run build
php artisan optimize        # includes panel:cache

Yang lebih tepat ditambahkan ke CI:

php artisan panel:assets    # exits 0 always; read the counts
php artisan panel:icons --check

panel:assets sengaja selalu keluar dengan code 0. Conflict bisa berasal dari perubahan yang memang sengaja dibuat aplikasi, sehingga menjadikannya failure default dapat mematahkan deploy yang sebenarnya valid. Jika CI Anda ingin gagal pada conflict, baca report melalui API:

use PandaPanel\Support\Installer\AssetManifest;

$conflicts = array_keys(array_filter(
    AssetManifest::compare(),
    static fn (array $entry): bool => $entry['status'] === AssetManifest::CONFLICT,
));

exit($conflicts === [] ? 0 : 1);

Rollback

composer require chocoalano/panel:0.1.1
php artisan optimize:clear
npm run build

Ada tiga jenis state yang tidak otomatis kembali:

• Published assets. File tersebut adalah milik aplikasi, jadi restore dari Git. Jalankan git checkout <ref> -- resources/js resources/css/panda-panel.css, lalu git checkout <ref> -- .panel-assets.json agar manifest kembali sesuai dengan file di disk.
• Migration. php artisan migrate:rollback menjalankan down() milik version lama. Table notifications yang tidak dibuat package sekarang sengaja dibiarkan tetap ada; package memeriksa ownership sebelum drop dan hanya menghapus ketika kepemilikan benar-benar jelas.
• Config key yang sudah dipublish. Key yang sudah dihapus upstream tetap berada di config aplikasi dan akan diabaikan.

Rollback frontend dan package PHP secara bersamaan. Menjalankan published tree dari release lebih baru terhadap PHP side yang lebih lama adalah kombinasi yang tidak diuji.

Hal yang perlu diperhatikan

• npm run build adalah bagian dari upgrade, bukan optimasi tambahan. Published Vue file merupakan source. Browser tidak menerima perubahannya sampai build dijalankan.
• Config di-merge, sehingga config key baru langsung memiliki default. mergeConfigFrom() berjalan saat register. Config yang dipublish setahun lalu tetap dapat menerima default baru. Jika ingin melihat key baru pada file aplikasi sendiri, gunakan diff -u config/panda-panel.php vendor/chocoalano/panel/config/panda-panel.php.
• vendor:publish --tag=panda-panel-config --force menimpa config aplikasi. Tidak ada merge. Lihat diff terlebih dahulu.
• vendor:publish --force bukan tool yang tepat untuk frontend setelah instalasi pertama. Command tersebut tidak dapat membedakan file kustom dari file stale; itulah fungsi utama panel:assets.
• Jalankan panel:icons setelah panel:assets --force, bukan sebelumnya. --force menulis salinan package dari icons/registry.ts di atas registry yang sudah dihasilkan panel Anda.
• Cached config dapat menyembunyikan perubahan config. Jalankan php artisan config:clear, atau optimize:clear yang sekaligus membersihkan panel manifest.
• Plugin dapat menghentikan seluruh application boot. Constraint requiresPanel yang tidak terpenuhi melempar exception saat registration sehingga seluruh route dan Artisan command gagal sampai plugin di-update atau dilepas.
• Meng-upgrade Laravel dan package ini dalam satu langkah membuat failure sulit diisolasi. Lakukan dalam dua commit terpisah.

Lihat juga

• Breaking changes — semua perubahan yang membutuhkan edit, lengkap dengan fix
• Kebijakan versioning — apa yang dijanjikan version number
• Manifest asset, Menyelesaikan konflik asset
• Changelog, Release checklist
• Migrasi nama package
• panel:assets, panel:install, panel:icons, panel:cache, panel:clear, panel:plugins
• Publish tags, Migrations
• Memperbarui published assets
• Production checklist, Frontend build, Rollback
• Compatibility