Menjalankan panel:install

Ini adalah command utama yang dijalankan pada instalasi baru. Semua yang dilakukannya tersedia sebagai command terpisah — vendor:publish berdasarkan tag, make:panel, dan panel:user — sehingga tidak ada langkah tersembunyi yang tidak dapat Anda jalankan atau ulangi sendiri. Command ini ada karena urutan langkah penting, dan instalasi yang berhenti satu langkah sebelum benar-benar dapat digunakan pada praktiknya sama dengan instalasi yang gagal.

php artisan panel:install

Signature

panel:install
    {--panel=Admin : The name of the first panel to scaffold}
    {--no-panel : Publish and configure without scaffolding a panel}
    {--no-user : Skip the offer to create a signing-in account}
    {--force : Overwrite files that already exist}

Option	Default	Efek
--panel=	Admin	Nama yang diteruskan ke make:panel. Nama diubah menjadi StudlyCase di sana, sehingga admin dan Admin berarti Panel yang sama.
--no-panel	off	Hanya publish dan konfigurasi, tanpa membuat scaffold Panel. Cocok ketika package dipasang ke aplikasi yang sudah memiliki Panel sendiri.
--no-user	off	Melewati seluruh prompt pembuatan account.
--force	off	Diteruskan ke vendor:publish dan make:panel: file yang sudah ada akan ditimpa.

Command selalu mengembalikan exit code 0. Pekerjaan yang tidak dapat dilakukan otomatis dilaporkan sebagai outstanding work, bukan sebagai kegagalan command. Shell yang menganggap "Anda masih perlu menjalankan npm install" sebagai build failure justru dapat menghentikan deployment karena alasan yang salah.

php artisan panel:install --panel=Support
php artisan panel:install --no-panel
php artisan panel:install --panel=Admin --no-user --no-interaction
php artisan panel:install --force

Enam Langkah Installer

1. Publish

$this->publish('panda-panel-config');   // vendor:publish --tag=panda-panel-config
$this->publish('panda-panel-assets');   // vendor:publish --tag=panda-panel-assets

Keduanya dijalankan dengan nilai --force yang Anda berikan. Setelah itu asset manifest ditulis:

use PandaPanel\Support\Installer\AssetManifest;

AssetManifest::write(AssetManifest::read());

Manifest menyimpan keadaan file yang baru saja dipublish. Data inilah yang memungkinkan panel:assets di kemudian hari membedakan file yang diedit aplikasi dari file yang hanya tertinggal versi. Tanpa baseline ini, upgrade berikutnya selalu menjadi pilihan buruk antara menimpa perubahan aplikasi atau tidak memperbarui apa pun.

Migration tidak langsung dipublish; installer hanya menawarkan pilihan:

Publish the migrations into database/migrations? (yes/no) [no]
❯ They already run from the package. Publish only to own them, and set load_migrations
  to false in config/panda-panel.php if you do.

Prompt ini ada karena published copy dan package copy dari migration yang sama berarti schema yang sama berpotensi diterapkan dua kali. Pada mode non-interactive, jawabannya otomatis no.

2. Scaffold Panel

$this->call('make:panel', ['name' => $panel, '--force' => (bool) $this->option('force')]);

Langkah ini dilewati sepenuhnya jika menggunakan --no-panel. Dalam kondisi tersebut langkah 3 dan 6 juga tidak memiliki Panel untuk diproses: tidak ada Panel yang diregistrasikan, dan panel:user dijalankan tanpa --panel untuk access report.

3. Register ke Config

Inilah langkah yang membuat URL Panel benar-benar dapat dijawab. Installer melakukan edit tekstual pada config/panda-panel.php — baris yang sama dan lokasi yang sama seperti jika developer menulisnya manual. Pendekatan tekstual dipilih karena file config sebagian besar berisi komentar yang menjelaskan setiap key; jika config diparse lalu ditulis ulang dari array, semua komentar tersebut hilang.

use PandaPanel\Support\Installer\PanelRegistrar;

PanelRegistrar::register('App\Panels\Admin\AdminPanelProvider');

/**
 * @param  class-string  $provider
 * @param  string|null   $path  the config file, defaulting to config_path('panda-panel.php')
 * @return self::*
 */
public static function register(string $provider, ?string $path = null): string

Ada empat outcome dan masing-masing dilaporkan berbeda:

Constant	Value	Kapan Terjadi	Laporan Installer
PanelRegistrar::REGISTERED	registered	Baris berhasil ditulis, atau placeholder yang sebelumnya dikomentari berhasil diaktifkan.	Registered … in config/panda-panel.php.
PanelRegistrar::ALREADY_PRESENT	already-present	Provider sudah memiliki entry aktif. Tidak ada file yang diubah.	That panel is already registered…
PanelRegistrar::NO_CONFIG	no-config	config/panda-panel.php tidak ada.	Outstanding: tambahkan entry secara manual.
PanelRegistrar::UNRECOGNISED	unrecognised	Bentuk array panels sudah berbeda dari config bawaan, misalnya dibangun dari variable atau direstrukturisasi.	Outstanding: tambahkan entry manual. File dibiarkan tidak berubah.

Tiga detail penting:

• Config bawaan sudah memiliki // App\Panels\Admin\AdminPanelProvider::class, dalam keadaan dikomentari. Jika baris komentar tersebut dianggap "sudah terdaftar", installer akan melaporkan sukses tetapi Panel tetap tidak dapat diakses — tepat masalah yang ingin dicegah. Karena itu baris komentar di-uncomment; entry aktif dibiarkan.
• Panel kedua ditambahkan di akhir, bukan di awal. Urutan registration menentukan Panel default ketika request tidak menyebut Panel tertentu. Panel baru ditempatkan terakhir, sama seperti developer biasanya menambahkannya secara manual.
• Config yang sudah direstrukturisasi tidak pernah ditebak. Jika key panels dibangun melalui variable, installer menganggap developer sedang mengelola config sendiri dan tidak mencoba memodifikasinya.

4. Melaporkan Home Redirect

Signed-in visitors to /dashboard now land in the panel. Set home_redirect.enabled to false
in config/panda-panel.php to keep your own.

Pesan ini dicetak, bukan ditanyakan. Ini adalah satu behavior yang berubah pada screen yang sebelumnya sudah dimiliki aplikasi, dan redirect yang tidak diberitahukan kepada developer akan berakhir sebagai bug report. Pesan tidak ditampilkan jika home_redirect.enabled false atau daftar path kosong.

5. Memeriksa Frontend

Ada enam check, dijalankan dalam urutan berikut. Setiap failure dimasukkan ke daftar outstanding work, bukan langsung dicetak di tengah proses.

Check	Method	Pesan Outstanding
Inertia	FrontendRequirements::missingInertia()	Menyebut root view atau middleware yang hilang dan menjelaskan bahwa seluruh screen Panel akan 500 tanpanya.
Vite	FrontendRequirements::hasVite()	Menjelaskan bahwa published component adalah Vue dan harus dibuild oleh tool seperti Vite.
Dependency list dapat dibaca	FrontendRequirements::hasNpmManifest()	Menyebut lokasi package.json package yang seharusnya tersedia dan menjelaskan bahwa npm dependency sama sekali tidak dapat diperiksa — ini packaging fault, bukan kesalahan aplikasi.
npm dependency	FrontendRequirements::missingNpmPackages()	Mencetak literal command npm install … untuk dependency yang belum dideklarasikan, lalu npm run build.
Layout override	FrontendRequirements::layoutOverrides()	Menyebut file, line number, offending code, dan replacement yang benar.
Host modules	FrontendRequirements::missingHostModules()	Daftar specifier @/…, serta menyebut wayfinder:generate untuk bagian yang generated.

Layout check perlu dipahami karena failure-nya silent. Setiap Page Panel mendeklarasikan layout sendiri melalui defineOptions({ layout: PanelLayout }). Jika application entry melakukan assignment layout tanpa kondisi, pilihan tersebut ditimpa setelah Page memilih layout:

page.default.layout = AppLayout;      // reported: every panel screen renders in your shell
page.default.layout ??= AppLayout;    // correct
page.default.layout ||= AppLayout;    // correct

Jika dibiarkan, seluruh Page Panel muncul di dalam shell aplikasi sendiri — menggunakan sidebar aplikasi dan tanpa Panel navigation — namun HTTP response tetap 200 dan log tidak menunjukkan error. Installer memeriksa resources/js/app.ts, app.js, ssr.ts, dan ssr.js untuk kasus ini.

Missing host module sengaja dicetak sebagai daftar nama, bukan hanya jumlah. Nama yang hilang menentukan solusi: jika seluruh @/routes/* dan @/actions/* hilang, Wayfinder belum dijalankan; jika hanya beberapa component hilang, kemungkinan aplikasi bukan Laravel Vue starter kit.

6. Menawarkan Pembuatan User

Create a user who can sign in? (yes/no) [no]

Installer menawarkan pilihan, bukan membuat account secara otomatis. Aplikasi yang sudah memiliki user tidak membutuhkan account baru, dan installer tidak seharusnya menulis row ke User Model aplikasi tanpa izin. Jika dijawab yes, installer menjalankan panel:user --panel={panel} menggunakan nama Panel yang diturunkan ke lowercase, sehingga account baru langsung diperiksa terhadap Panel yang baru dibuat.

Langkah ini dilewati dengan --no-user dan juga dilewati jika input bukan interactive terminal.

Laporan Akhir

Jika tidak ada pekerjaan manual:

Done. Nothing is left to do by hand.

Jika masih ada pekerjaan:

WARN  3 thing(s) this package cannot do for your application:

  1. Install the npm dependencies the components import, then rebuild:
     …
  2. resources/js/app.ts line 12 overwrites the layout every panel page declares:
     …
  3. The published components import these modules, which belong to your application
     and are not there yet:
     …

Semua temuan dikumpulkan selama proses dan dicetak satu kali di akhir. Installer yang mencampur lima pesan sukses dengan tiga warning di tengah output membuat warning mudah dianggap noise dan terlewat.

Yang Tidak Dilakukan Installer

Tidak Dilakukan	Alasan
npm install / npm run build	Installer memberi command yang tepat. Menjalankan package manager dari dalam Artisan command merupakan side effect yang tidak diminta developer.
php artisan wayfinder:generate	Wayfinder adalah tool aplikasi dan bekerja terhadap route aplikasi. Installer hanya menyebut command tersebut ketika generated module hilang.
php artisan migrate	Ini workflow standar Laravel; jalankan ketika Anda siap.
Mendaftarkan guest redirect	Sudah dilakukan oleh service provider. Set register_guest_redirect => false jika ingin mengambil alih.
Mengedit resources/js/app.ts	Installer hanya melaporkan pola yang salah dan membiarkan source milik aplikasi tetap tidak disentuh.

Menjalankan Installer Ulang

Aman. Publish melewati file yang sudah ada, registration menjadi no-op jika Panel sudah terdaftar, make:panel melewati file yang akan ditimpa dan memberi laporan, sedangkan frontend check bersifat read-only.

Dengan --force, tingkat keamanannya berbeda: vendor:publish --force menimpa seluruh file hasil publish, termasuk file yang telah Anda modifikasi. Setelah instalasi pertama gunakan panel:assets, karena command tersebut dapat membedakan file stale dari file yang sengaja diubah aplikasi.

Catatan

• Exit code selalu 0. Jika Anda membuat script di sekitar installer, periksa output/outstanding work, bukan hanya status process.
• --no-interaction mengubah dua jawaban, bukan keseluruhan alur. Migration tidak dipublish dan user tidak ditawarkan; seluruh langkah lainnya tetap dijalankan sama.
• Daftar npm dibaca dari package.json package. Daftar tidak dapat menjadi stale terhadap dependency yang digunakan component karena tidak ada copy kedua.
• Installer menulis .panel-assets.json bahkan jika tidak ada file yang baru dipublish. Manifest merekam apa yang ada di disk, sehingga re-run setelah manual vendor:publish tetap menghasilkan baseline yang benar.

Lihat Juga

• Installation — langkah yang sama jika dijalankan manual
• Frontend requirements — seluruh check pada langkah 5
• Creating the first user — command yang dipanggil pada langkah 6
• Opening your first panel — langkah berikutnya setelah installer selesai
• Common install problems
• CLI: panel:install, CLI: panel:assets
• Configuration: home redirect, guest redirect