Instalasi

Dokumen ini menjelaskan proses memasukkan PandaBear ke dalam aplikasi: memasang package, mempublish konfigurasi, menyiapkan frontend, membuat Panel pertama, dan membuat account yang dapat sign-in. Pada aplikasi Laravel Vue starter kit, proses utamanya hanya dua command dan satu build.

Versi Singkat

composer require chocoalano/panel
php artisan panel:install
npm install
npm run build
php artisan serve

Setelah itu buka /admin. panel:install akan membuat scaffold Panel, meregistrasikannya, lalu pada akhir proses menyebutkan pekerjaan apa saja yang tidak dapat diselesaikan otomatis. Pada aplikasi starter kit, daftar tersebut biasanya kosong.

Apa yang Dilakukan composer require Secara Otomatis

Package mendeklarasikan service provider dan facade melalui composer.json, sehingga Laravel package discovery memasang keduanya tanpa perlu mengedit aplikasi:

"extra": {
    "laravel": {
        "providers": ["PandaPanel\\PandaPanelServiceProvider"],
        "aliases": { "PandaPanel": "PandaPanel\\Facades\\PandaPanel" }
    }
}

Saat boot, PandaPanel\PandaPanelServiceProvider meregistrasikan container bindings, Panel yang tercantum pada config/panda-panel.php (belum ada pada instalasi baru), empat middleware alias, middleware web, guest redirect, route group, migration package, publish tag, dan Artisan command. Pada tahap ini belum ada Panel yang diregistrasikan, sehingga belum ada URL Panel yang dapat dijawab.

Langkah demi Langkah

panel:install menjalankan langkah berikut secara berurutan. Setiap langkah juga tersedia sebagai command terpisah, sehingga tidak ada proses tersembunyi yang tidak dapat Anda jalankan atau ulangi secara manual.

1. Publish Konfigurasi

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

Command ini menulis config/panda-panel.php. Sebagian besar isi file berupa komentar yang menjelaskan setiap key; daftar key secara lengkap tersedia pada configuration reference.

Package melakukan merge terhadap config internal pada tahap register, sehingga setiap key tetap memiliki nilai bahkan sebelum file dipublish. Namun publish sangat penting untuk satu key: panels. Sebuah Panel harus terdaftar di array tersebut sebelum URL-nya dapat digunakan.

2. Publish Frontend

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

Terdapat tujuh source yang didefinisikan satu kali di PandaPanel\Support\Installer\PublishedAssets::map() dan dibaca oleh vendor:publish maupun panel:assets:

Dari Package	Ke Aplikasi Anda
resources/js/panel	resources/js/panel (configurable — frontend.panel_path)
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

Frontend dipublish ke aplikasi, bukan diimpor langsung dari package, karena setiap component registry merupakan build-time allowlist berbasis import.meta.glob terhadap tree aplikasi. Component yang tidak pernah dilihat oleh build tidak dapat di-resolve. Setelah dipublish, file tersebut menjadi milik aplikasi: masuk repository, ikut build, dan boleh diedit.

vendor:publish tidak menimpa file yang sudah ada tanpa --force, sehingga component milik starter kit pada resources/js/components/* tetap aman.

3. Publish Migration, atau Tidak

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

Langkah ini opsional dan secara default dijawab "tidak" oleh installer. Migration sebenarnya sudah dijalankan langsung dari package; publish hanya menentukan ownership, bukan menentukan apakah table akan dibuat. Jika Anda mempublish migration, set load_migrations ke false — published copy dan package copy dari migration yang sama berarti schema yang sama berpotensi diterapkan dua kali.

Setelah itu jalankan:

php artisan migrate

4. Scaffold Panel Pertama

php artisan make:panel Admin
php artisan make:panel Admin --path=back-office

Command ini menulis app/Panels/Admin/AdminPanelProvider.php dan tiga directory yang akan dipindai oleh discovery. Masing-masing diberi .gitkeep karena Git tidak melacak directory kosong; tanpa file tersebut, provider dapat menunjuk ke path yang hilang setelah repository di-clone.

app/Panels/Admin/
├── AdminPanelProvider.php
├── Pages/.gitkeep
├── Resources/.gitkeep
└── Widgets/.gitkeep

5. Register Panel

Panel diregistrasikan melalui daftar eksplisit, bukan auto-discovery. Urutan registration menentukan Panel mana yang menjadi tujuan default user ketika request tidak menyebut Panel tertentu. Menambahkan Panel seharusnya merupakan perubahan yang disengaja, bukan side effect dari keberadaan file di filesystem.

// config/panda-panel.php
'panels' => [
    App\Panels\Admin\AdminPanelProvider::class,
],

panel:install menulis entry tersebut untuk Anda — lihat Running panel:install untuk seluruh outcome dan behavior saat config sudah direstrukturisasi. make:panel jika dijalankan sendiri hanya menampilkan baris yang harus ditambahkan, karena generator yang diam-diam mengedit config dapat membuat urutan Panel sulit dilacak.

Tanpa langkah ini, instalasi terlihat selesai dan provider memang ada, tetapi URL Panel menghasilkan 404. Ini adalah penyebab paling umum dari kasus "package sudah terpasang tetapi tidak bekerja".

6. Install npm Dependency dan Build

npm install
npm run build

Daftar tepat dependency yang belum tersedia di project Anda dicetak oleh panel:install dan dibaca langsung dari package.json package. Lihat Frontend requirements untuk daftar lengkap serta module @/ yang memang menjadi tanggung jawab aplikasi, bukan package.

7. Buat User yang Dapat Sign-In

php artisan panel:user
php artisan panel:user --name=Ada --email=ada@example.com --password=correct-horse --panel=admin

Account dibuat melalui User Model milik auth guard yang dipilih, bukan melalui model yang di-hard-code oleh command. Lihat Creating the first user.

Daftar Lengkap Publish Tag

Tag	Yang Dipublish
panda-panel-config	config/panda-panel.php
panda-panel-assets	Frontend seperti pada tabel sebelumnya
panda-panel-migrations	database/migrations
panda-panel-stubs	stubs/panel — template yang dibaca seluruh generator
panda-panel	Config, migration, dan asset sekaligus. Tidak termasuk stub.

Mem-publish stub memungkinkan project mengubah template yang digunakan generator. Jika aplikasi memiliki copy stub sendiri, copy tersebut selalu diprioritaskan; package stub hanya digunakan jika tidak ada copy aplikasi.

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

Verifikasi Instalasi

php artisan route:list --name=panel.
php artisan panel:cache        # discovery once, reported by count
php artisan panel:clear

route:list seharusnya menampilkan panel.admin.dashboard pada /admin, serta guest route milik Panel yang menggunakan ->auth() dan ->login() di bawah prefix yang sama.

panel:cache menampilkan jumlah Panel, Resource, Page, dan Widget yang berhasil ditemukan. Jika suatu kategori menunjukkan 0 padahal Anda mengharapkan class tertentu, kemungkinan discovery path tidak sesuai dengan lokasi class sebenarnya.

Setelah sign-in, user diarahkan ke Panel, bukan ke starter kit placeholder dashboard. Request /dashboard diarahkan ke Panel pertama yang dapat dimasuki user.

Instalasi Non-Interactive

Dua prompt — publish migration dan membuat user — dilewati jika input bukan interactive terminal. Dengan demikian scripted install tidak pernah menggantung menunggu jawaban yang tidak akan datang.

php artisan panel:install --panel=Admin --no-user --no-interaction
php artisan panel:user --name=Ada --email=ada@example.com --password="$ADMIN_PASSWORD"

Catatan

• --force mempublish ulang seluruh file, termasuk file yang sudah Anda edit. Setelah instalasi pertama, gunakan panel:assets untuk upgrade. Command tersebut mengetahui file mana yang Anda ubah karena .panel-assets.json menyimpan keadaan setiap file ketika dipublish.
• Commit .panel-assets.json. File ini adalah catatan versi frontend Panel yang dipublish oleh aplikasi. Tanpanya, upgrade tidak dapat membedakan perubahan aplikasi dari copy yang hanya tertinggal versi.
• Instalasi tidak melakukan build frontend. Component dibuat dengan Vue; npm run build atau npm run dev yang menghasilkan asset yang dapat dimuat browser. Panel yang muncul sebagai HTML tanpa styling biasanya berarti build belum dijalankan.
• Resource baru akan 403 sampai model memiliki policy. Authorization gate ditanya dan secara default menjawab tidak. Ini disengaja — jauh lebih aman daripada menampilkan seluruh record hanya karena developer belum menulis policy. Pada development, Panel mencatat model mana yang belum memiliki policy.

Lihat Juga

• Running panel:install — seluruh option, langkah, dan laporan installer
• Requirements dan Compatibility
• Frontend requirements — npm package, host module, dan build
• Laravel Vue starter kit setup
• Creating the first user
• Opening your first panel
• Directory structure
• Common install problems
• CLI: publish tags, CLI: make:panel
• Configuration reference