Installer Laravel Package

Getting Started

This release (v0.0.4) is the Filament v4 compatibility line. Treat it as the minimum version to install on any Filament v4 panel; earlier tags target v3 and will not boot against v4's schema/action namespaces.

composer require <vendor>/<package>:"^0.0.4"
php artisan vendor:publish --tag="<package>-config"
php artisan vendor:publish --tag="<package>-migrations"
php artisan migrate

Then register the plugin on the panel you actually use, in app/Providers/Filament/AdminPanelProvider.php:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Vendor\Package\PackagePlugin::make(),
        ]);
}

Where to look first, in order:

1. config/<package>.php — almost everything day-to-day is toggled here (navigation group, feature flags, table names, route prefix).
2. The published migrations — confirm table names don't collide with your existing schema before running them in anything other than local.
3. The plugin class itself — see which resources/pages/widgets it registers and whether they land in the panel automatically or need opt-in.

First realistic use case: install locally, register the plugin, log into /admin, and confirm the plugin's pages/widgets appear in the navigation. That single smoke test validates the v4 wiring (panel registration, asset loading, Livewire 3 compatibility) before you invest in configuration.

Implementation Patterns

Panel-scoped registration. Only register the plugin on the panels that need it. In a multi-panel app (AdminPanelProvider, AppPanelProvider), registering globally via a service provider is the most common source of "why does this show up in the customer portal" bugs. Keep ->plugins([...]) explicit per panel.

Compose with v4 schemas, don't fight them. Filament v4 unified forms and infolists under Filament\Schemas\Schema. When the package exposes form components, drop them into your resource's schema method rather than wrapping them in your own Form object:

use Filament\Schemas\Schema;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        // your fields
        ...PackagePlugin::formComponents(),
    ]);
}

Actions live in Filament\Actions. If the package ships table or page actions, the v4 namespaces apply — don't copy v3 snippets from the package's older docs or from blog posts, they'll fatal on class-not-found.

Config over forking. Most plugin behaviour (labels, navigation sort, tenancy scoping, feature toggles) is exposed through the config file. Publish it, commit it, and change it there. Forking the package for a label tweak is the fastest way to make the next 0.0.x bump painful.

Testing. Use Filament's panel test helpers so the plugin's pages resolve in the test panel:

use Livewire\Livewire;

it('renders the plugin page', function () {
    $this->actingAs(User::factory()->create());

    Livewire::test(\Vendor\Package\Pages\SomePage::class)
        ->assertSuccessful();
});

Add a test that hits the panel root as an authenticated user — it catches registration and asset-pipeline regressions cheaply.

Upgrade workflow. Because this is a 0.0.x line, pin exactly ("^0.0.4" at most) and read the diff between tags before bumping. Run php artisan optimize:clear and php artisan filament:assets after every update, then re-run your panel smoke test.

Gotchas and Tips

• v4 is not a drop-in for v3 code. If you're upgrading an existing install, Filament\Forms\Form → Filament\Schemas\Schema, and table/page actions moved to Filament\Actions. Any local override or published view copied from a v3 install will break silently or throw Class not found.
• Tailwind v4 for custom themes. If you have a custom Filament theme, v4 expects Tailwind v4 and @source directives pointing at vendor views. A stale compiled theme is the usual cause of "the plugin's UI looks unstyled" — rebuild with npm run build, don't just clear caches.
• Assets after every composer update. php artisan filament:assets (and vendor:publish --force for the package's public assets) is not optional; forgetting it produces 404s on JS/CSS that look like package bugs.
• Component caching. Filament caches discovered components. In production use php artisan filament:optimize; when debugging missing pages/widgets locally, run php artisan filament:clear-cached-components before assuming the plugin is broken.
• Publish tags are versioned. Re-publishing migrations after an upgrade can overwrite nothing or produce duplicates depending on the tag. Diff published migrations against the vendor copy after each bump; never blindly --force migrations in a deployed environment.
• Config cache in production. config/<package>.php changes need php artisan config:cache re-run. Plugin registration lives in the panel provider, so it's covered by optimize, but published config is not.
• Multi-tenancy scoping. If the plugin ships resources and your panel uses tenancy, verify the resource queries are scoped — plugin resources don't always inherit your tenant() model automatically in 0.0.x releases.
• Pre-1.0 API churn. At 0.0.x, public methods and config keys can change between patches. Wrap any direct calls into package classes in a thin adapter or service of your own so a rename is a one-file fix.
• Debugging order of operations: php artisan about (confirm Filament + Laravel versions) → check the panel provider actually registers the plugin → filament:clear-cached-components → optimize:clear → rebuild assets. That sequence resolves the large majority of "it worked yesterday" reports.