Instalasi dari Packagist

Package Composer-nya adalah chocoalano/panel, dan yang diinstal merupakan subset dari repository ini: src, config, database, resources, dan stubs, ditambah composer.json, README, dan licence. File lainnya menggunakan export-ignore dan tidak pernah sampai ke aplikasi. Gunakan halaman ini ketika composer require gagal, package berhasil terpasang tetapi tidak ada yang teregistrasi, atau panel:install memberikan laporan yang lebih sedikit dari seharusnya.

Instalasi

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

Sebelum menyimpulkan hal lain, pastikan versi dan source yang benar-benar di-resolve Composer:

composer show chocoalano/panel
composer why chocoalano/panel

Report tersebut menampilkan versi yang terpasang, source asalnya, dan mapping PSR-4 PandaPanel\ => src/ yang digunakan seluruh framework untuk autoload. composer why menunjukkan package apa yang menarik dependency ini, sehingga instalasi transitif melalui package lain mudah diketahui.

1. Composer tidak menemukan package

Pesan Composer	Penyebab
Could not find a matching version of package chocoalano/panel	Nama package benar, tetapi constraint tidak dapat dipenuhi atau release belum stabil
it could not be found in any version, there may be a typo in the package name	Nama salah, atau repository yang dibaca Composer tidak memiliki package tersebut
Tidak ada hasil untuk panda/panel	Itu nama lama. Package sudah berganti nama dan tidak ada metapackage yang mengalias nama lama

Vendor Composer-nya adalah chocoalano, bukan panda, sementara namespace PHP tetap PandaPanel\. Keduanya memang tidak sama dan tidak dimaksudkan untuk sama. Aplikasi yang masih menggunakan nama lama hanya perlu mengubah satu baris; lihat migrasi nama package.

composer clear-cache
composer diagnose

Stability adalah penyebab lain dari kondisi "package ditemukan tetapi tidak dapat di-resolve". Package menetapkan "minimum-stability": "stable" dan "prefer-stable": true untuk dependency-nya sendiri, tetapi minimum-stability milik aplikasi root yang menentukan apakah tag pre-release boleh menjadi kandidat instalasi.

Untuk memasang dari git checkout alih-alih Packagist—juga berguna untuk menguji fork:

{
    "repositories": [
        { "type": "path", "url": "../panda-panel" }
    ],
    "require": {
        "chocoalano/panel": "*"
    }
}

Path repository menggunakan symlink secara default, sehingga seluruh repository terlihat—termasuk file yang seharusnya dibuang dari dist archive. Perbedaan ini dibahas pada bagian 4 dan menjelaskan mengapa package dapat bekerja sempurna melalui path repository tetapi kehilangan sesuatu ketika dipasang dari Packagist.

2. Composer menolak me-resolve requirements

"require": {
    "php": "^8.2",
    "ext-json": "*",
    "ext-zip": "*",
    "composer-runtime-api": "^2.2",
    "composer/semver": "^3.0",
    "inertiajs/inertia-laravel": "^3.0",
    "laravel/framework": "^12.0|^13.0",
    "laravel/fortify": "^1.37.2",
    "symfony/finder": "^7.0|^8.0"
}

Pesan menyebut	Penyebab
requires php ^8.2	PHP di bawah 8.2
requires ext-zip	Extension zip belum terpasang. Ini requirement wajib—file XLSX adalah zip archive, dan gagal pada saat instalasi jauh lebih mudah ditangani daripada gagal saat runtime
laravel/framework[v11.x] … does not match your constraint	Laravel 11 tidak didukung dan tidak dapat didukung: seluruh release 11.x ditandai oleh advisory yang belum dipatch
PHP 8.2 dengan Laravel 13 tidak dapat di-resolve	Laravel 13 membutuhkan PHP 8.3. Aplikasi PHP 8.2 menggunakan Laravel 12
konflik laravel/fortify	Minimum ^1.37.2; security settings page dan emailed-code factor membaca feature flag milik Fortify

Tidak ada kode di src/ yang menggunakan package require-dev, sehingga --no-dev aman. Lihat compatibility matrix untuk kombinasi yang benar-benar dijalankan CI.

3. Package terpasang tetapi tidak ada yang teregistrasi

Gejala. vendor/chocoalano/panel tersedia, tetapi php artisan tidak menampilkan command panel:*.

Penyebab. Package discovery tidak berjalan. Discovery merupakan Composer script, sehingga --no-scripts melewatinya dan hasilnya terlihat sama seperti package tidak pernah diinstal.

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

php artisan package:discover
php artisan about --only=drivers

Tidak perlu menambahkan apa pun ke bootstrap/providers.php. Jika package discovery memang dinonaktifkan secara sengaja di aplikasi Anda, register provider tersebut secara manual di sana.

4. Isi dist archive

Packagist menyajikan git archive dari tag, dan .gitattributes menentukan file apa saja yang masuk. Reproduksi persis isi yang akan diterima aplikasi:

git archive --format=tar HEAD | tar -t | awk -F/ '{print $1}' | sort -u

LICENSE.md
README.md
composer.json
config/
database/
resources/
src/
stubs/

Ada di dist	Alasan
src/	framework, termasuk src/Testing; testing helper diautoload melalui files di composer.json
config/panda-panel.php	di-merge saat register dan dipublish melalui --tag=panda-panel-config
database/migrations	dimuat dari package kecuali load_migrations bernilai false
resources/js, resources/css	dipublish melalui --tag=panda-panel-assets
stubs/panel	digunakan seluruh generator, dan dipublish melalui --tag=panda-panel-stubs

Yang menggunakan export-ignore, sehingga tidak tersedia di dist: /docs, /tests, /examples, /frontend, /.github, CHANGELOG.md, phpstan.neon, phpunit.xml, pint.json, tsconfig.json, vite.config.ts, eslint.config.js, konfigurasi Prettier—serta package.json dan package-lock.json. package.json adalah file yang perlu diperhatikan secara khusus.

5. panel:install tidak melaporkan dependency npm yang perlu dipasang

Gejala. php artisan panel:install selesai dengan Done. Nothing is left to do by hand., kemudian npm run build gagal dengan Failed to resolve import "reka-ui", atau pesan serupa untuk package lain yang diimport komponen hasil publish.

Penyebab. Daftar dependency npm tidak diduplikasi di PHP. Daftar tersebut dibaca langsung dari package.json milik package ini pada copy yang terpasang di vendor/:

// PandaPanel\Support\Installer\FrontendRequirements::npmPackages()
$manifest = dirname(__DIR__, 3).'/package.json';

if (! File::exists($manifest)) {
    return [];
}

File yang tidak tersedia menghasilkan list kosong, bukan error. List kosong membuat missingNpmPackages() juga mengembalikan [], sehingga installer tidak memiliki apa pun untuk dilaporkan. Pemeriksaan tidak gagal; ia hanya menjadi diam.

Pastikan pada copy yang terpasang, bukan pada checkout repository:

ls vendor/chocoalano/panel/package.json

use PandaPanel\Support\Installer\FrontendRequirements;

FrontendRequirements::npmPackages();
// [] when package.json did not reach the dist
// ['@inertiajs/vue3@^3.0.0', '@internationalized/date@^3.12.0', …] when it did

Perbaikan di sisi package. /package.json tidak boleh menggunakan export-ignore, meskipun file toolchain frontend lainnya boleh. Lockfile, Vite config, tsconfig, dan lint config bersifat development-only dan benar jika dibuang; package.json dibaca installer saat runtime dan harus ikut didistribusikan.

  # .gitattributes
- /package.json      export-ignore
  /package-lock.json export-ignore

git archive --format=tar HEAD | tar -t | grep '^package.json'

Tidak ada output berarti archive tidak membawanya, sehingga copy yang diinstal juga tidak akan memilikinya. Test suite tidak menangkap kondisi ini: suite berjalan dari git checkout, tempat package.json tetap tersedia terlepas dari isi .gitattributes.

Workaround untuk aplikasi yang menggunakan release yang terlanjur tidak menyertakannya. Instal dari source agar seluruh repository masuk ke vendor/:

composer require chocoalano/panel --prefer-source

Atau pasang dependency secara manual. Daftarnya berasal dari block dependencies milik package.json package dan direproduksi lengkap di error build Vite serta frontend requirements:

npm install \
  @inertiajs/vue3@^3.0.0 @internationalized/date@^3.12.0 @laravel/echo-vue@^2.4.0 \
  @laravel/passkeys@^0.4.0 @lucide/vue@^1.31.0 @tailwindcss/vite@^4.1.0 \
  @tanstack/vue-table@^9.0.0 @vueuse/core@^14.0.0 class-variance-authority@^0.7.0 \
  clsx@^2.1.0 reka-ui@^2.0.0 tailwind-merge@^3.0.0 tailwindcss@^4.1.0 \
  tw-animate-css@^1.2.0 vue@^3.5.0 vue-input-otp@^0.4.0 vue-sonner@^2.0.0
npm run build

Node harus >=20.19, sesuai engine range package.

Dua method yang menangani proses ini

Method	Signature	Membaca
npmPackages	static npmPackages(): list<string>	package.json milik package, hanya dependencies, sebagai name@range, diurutkan
missingNpmPackages	static missingNpmPackages(): list<string>	package.json milik aplikasi, dependencies dan devDependencies, lalu melakukan filter

use PandaPanel\Support\Installer\FrontendRequirements;

FrontendRequirements::missingNpmPackages();
// ['@lucide/vue@^1.31.0', 'reka-ui@^2.0.0']

missingNpmPackages() membaca package.json milik aplikasi, bukan node_modules, karena yang penting adalah dependency dideklarasikan oleh project. Transitive dependency yang kebetulan tersedia hari ini bisa hilang saat package lain diupgrade. Aplikasi tanpa package.json dilaporkan kehilangan seluruh dependency.

6. vendor:publish tidak menemukan asset untuk dipublish

Penyebab. Publish map dibangun dari PandaPanel\Support\Installer\PublishedAssets::map(), yang menunjuk ke directory di dalam package terpasang. Dist yang tidak membawa resources/js tidak memiliki apa pun untuk dipublish; hal yang sama berlaku jika --tag yang diberikan tidak ada.

php artisan vendor:publish --tag=panda-panel-assets
ls vendor/chocoalano/panel/resources/js/panel | head

use PandaPanel\Support\Installer\PublishedAssets;

PublishedAssets::map();        // absolute package source => absolute application destination
PublishedAssets::files();      // absolute destination => absolute source, per file

Tag	Yang dipublish
panda-panel-config	config/panda-panel.php
panda-panel-assets	tujuh source frontend
panda-panel-migrations	database/migrations
panda-panel-stubs	stubs/panel
panda-panel	config, migration, dan asset sekaligus — tidak termasuk stubs

Penyebab umum kedua bukan archive: vendor:publish melewati file yang sudah tersedia. Setelah instalasi pertama, gunakan panel:assets, yang mengetahui file mana yang pernah Anda edit karena .panel-assets.json merekam kondisi setiap file saat dipublish.

7. Versi yang terpasang dan package yang bergantung padanya

Versi framework dibaca dari data installed-packages milik Composer menggunakan nama package yang dikenal Composer:

use Composer\InstalledVersions;

InstalledVersions::getPrettyVersion('chocoalano/panel');   // '1.0.0'

php artisan panel:plugins
php artisan panel:plugins --panel=admin

PandaPanel\Plugins\PluginCompatibility menggunakan lookup yang sama untuk mengevaluasi constraint requiresPanel milik plugin. Sebuah test membandingkan constant PACKAGE dengan name pada composer.json, sehingga perubahan nama di masa depan tidak dapat mematikan pemeriksaan tersebut secara diam-diam:

$reflection = new ReflectionClass(PluginCompatibility::class);

expect($reflection->getConstant('PACKAGE'))
    ->toBe(json_decode(file_get_contents(base_path('composer.json')), true)['name']);

Ada tiga kondisi yang melewati pemeriksaan constraint dan semuanya berarti memang tidak ada pertanyaan yang perlu dijawab: plugin tidak mendeklarasikan constraint, framework tidak terpasang sebagai Composer package (misalnya path repository atau git checkout), dan branch alias seperti dev-main yang tidak dapat dievaluasi terhadap constraint versi.

8. Instalasi saat deployment

composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction
php artisan optimize
npm ci && npm run build

Flag	Efek di sini
--no-dev	melewati Pest, Pint, Larastan, Mockery, dan Testbench—tidak ada yang digunakan src/
--prefer-dist	mengunduh archive, bukan clone; inilah alasan bagian 4 penting
--optimize-autoloader	menghasilkan classmap agar discovery dapat resolve class tanpa filesystem probe
--no-scripts	hindari — package discovery merupakan Composer script

Jalankan composer install terlebih dahulu, baru panel:cache: discovery me-resolve file path melalui PSR-4 map milik Composer, dan manifest yang dibuat dengan autoloader lama dapat menunjuk class yang sudah berpindah.

Hal yang perlu diperhatikan

• --prefer-dist dan --prefer-source memasang tree yang berbeda. Dist mengikuti export-ignore; source adalah clone dan membawa semuanya. Bug yang hanya muncul pada salah satunya hampir selalu berkaitan dengan isi archive.
• composer.json di dist tetap mendeklarasikan autoload-dev untuk tests/ dan examples/, meskipun directory tersebut tidak ada di archive. Ini tidak masalah—autoload-dev hanya berlaku untuk root package, bukan dependency.
• Repository dan framework tetap bernama Panda Panel. Yang berubah hanya vendor namespace Composer; config/panda-panel.php, PandaPanel\, publish tag, dan route name tetap sama.
• CHANGELOG.md tidak ada di dist. Baca dari repository atau release page; copy yang terpasang memang tidak memiliki changelog.
• docs/ juga tidak ada di dist. Halaman dokumentasi ini berada di repository.
• Package npm @chocoalano/panel memiliki private: true dan tidak pernah dipublish. Itu adalah toolchain repository ini; komponen masuk ke aplikasi melalui vendor:publish.
• package-lock.json sengaja tidak didistribusikan. Lockfile repository mengunci toolchain development milik package; aplikasi memasang dependency berdasarkan range versinya sendiri.
• Path repository mematikan pemeriksaan constraint requiresPanel pada setiap plugin secara diam-diam. Perilaku ini tepat untuk monorepo, tetapi tidak tepat untuk staging yang dimaksudkan meniru production.

Lihat juga

• Instalasi, requirements, compatibility matrix
• Migrasi nama package, panduan upgrade, versioning
• Composer dan autoloading, production checklist
• Frontend requirements, menjalankan panel:install
• panel:install, panel:assets, publish tags, panel:plugins
• Kompatibilitas plugin
• Error build Vite, host module yang hilang, Tailwind 4
• Masalah instalasi umum