Skip to content

Debugging Package Discovery

Use this when a package is installed with Composer but Capell cannot see its commands, settings, admin surfaces, frontend output, or Marketplace metadata.

Discovery Flow

flowchart LR
    Composer["composer show package"] --> Autoload["PSR-4 autoload"]
    Autoload --> Provider["Laravel provider discovery"]
    Provider --> Manifest["capell.json loaded"]
    Manifest --> Registry["Capell package registry"]
    Registry --> Bucket["Provider bucket for context"]
    Bucket --> Surface["Admin/frontend/settings/cache contribution"]

Debug left to right. Do not start by editing UI code until Composer, autoload, provider discovery, and manifest state are proven.

First Checks

composer show capell-app/example
composer dump-autoload -o
php artisan optimize:clear
php artisan capell:package-cache:clear
php artisan list capell

If the package comes from a private repository or local path repository:

composer config repositories
composer show capell-app/example --available

Symptom Table

Symptom	Likely cause	Check	Fix
Composer cannot find package	Repository/auth/path config missing	`composer config repositories`	Add repository/auth or local path repo, then `composer clear-cache`.
Composer installs package but classes fail	PSR-4 namespace mismatch	`composer dump-autoload -o` output	Fix `composer.json` autoload namespace/path.
Laravel never boots provider	Provider discovery missing/disabled	`composer show -a package` and package `extra.laravel.providers`	Add provider discovery or register provider in host app.
Capell package state missing	`capell.json` invalid or package cache stale	Inspect manifest and clear package cache	Fix manifest v3 fields and run `php artisan capell:package-cache:clear`.
Admin surface missing only in browser	Admin provider not in admin bucket or config cache stale	Check `capell.json` providers and `php artisan optimize:clear`	Move Filament code to admin provider/AdminBridge.
Frontend output missing	Frontend provider not loaded or path not reserved	`php artisan route:list` and frontend registry tests	Register frontend provider, render hook, component, or reserved path.
Settings missing	Settings class/schema not registered	Inspect `SettingsSchemaRegistry` registrations	Register settings class and schema; run settings migration.

Manifest Checklist

The package manifest should answer:

What is the Composer package name?
What kind of package is it?
Which provider buckets should load in install/runtime/admin/frontend contexts?
Which settings group does it own?
Which product group/tier/bundle should Marketplace and docs show?
Which scopes does it require?

Older manifest fields such as capell-version are not supported. Use manifest version 3.

Test Recipe

it('registers package metadata and providers', function (): void {
    $package = CapellCore::getPackage('capell-app/example');

    expect($package->name)->toBe('capell-app/example')
        ->and($package->getLabel())->toBe('Example')
        ->and($package->hasAdminScope())->toBeTrue();
});

it('boots the package provider without writing host state', function (): void {
    expect(fn (): array => $this->app->getLoadedProviders())
        ->not->toThrow(Throwable::class);
});

Next