Evolutionkitv5 Laravel Package

Getting Started

The 5.9.0 release is a Filament v5.9.0 baseline bump plus a structural refactor ("Use user/admin packages for models, resources and login"), so the first step is confirming which Filament minor you are on and whether you are on the new split-package auth model.

1. Check your constraints. Require filament/filament:^5.9 alongside this package; CI now runs PHPStan on PHP 8.4, so PHP 8.4 is a supported runtime. If you are still on 5.8.x of the kit, read the 5.8.2...5.9.0 compare link before upgrading — the model/resource/login move is the only behavioural change in the release.
2. Install and publish. composer require the package, then run the install command documented in the README (typically php artisan evolutionkit:install) or publish manually: config, migrations, and assets. Re-publish assets after the Filament bump — php artisan filament:assets and php artisan filament:upgrade — because Filament's compiled CSS/JS hashes change between minors.
3. Register the plugin. Add the kit's plugin class to the panel() chain in your PanelProvider. If you have more than one panel, decide now which panel owns which resources; the 5.9.0 split between user-facing and admin-facing resources assumes a two-panel (or at least two-guard) layout.
4. First use case: stand up the admin panel, log in through the package-provided login rather than a hand-rolled Filament login page, and confirm one resource page renders end-to-end. That single vertical slice exercises config, migrations, plugin registration, and auth in one go.

Where to look first: the package config file (published to config/), the CHANGELOG entry for 5.9.0, and the PanelProvider snippet in the README. Do not start by reading source — the config keys tell you what is meant to be tunable.

Implementation Patterns

Two-panel layout. Post-5.9.0 the intended shape is an admin panel (admin package resources: user management, the kit's operational resources) and a user panel (user package resources: profile, self-service pages, login). Model this explicitly:

->plugin(EvolutionKitPlugin::make())
->discoveryEnabled(false) // when you want package resources only

Disable auto-discovery if you want a deterministic resource list; leave it on in greenfield apps.

Extend, don't fork. The kit's resources are ordinary Filament resources. Subclass them and re-register your subclass in the panel rather than editing vendor files:

class CustomerResource extends \Vendor\EvolutionKit\Resources\CustomerResource
{
    public static function getNavigationGroup(): ?string { return 'Operations'; }
}

Then remove the base class from the panel and add yours. This survives minor releases, which is exactly what 5.9.0 is.

Auth through the packages. Replace any local User model / login page with the ones shipped by the user/admin packages. Point config/auth.php at the package model, and if you have existing users, write a data migration rather than letting the package migration recreate the table.

Roles and policies. Use the admin package's role/permission surface, then write policies per resource — viewAny, create, update, delete — and register them in AuthServiceProvider. Filament will silently hide resources without a policy method returning true; that is the number one "my resource disappeared" cause.

Localization and navigation. Set navigation groups, sort order, and labels in your subclasses, not in config, so per-panel differences stay readable. Keep the config file for integration concerns (credentials, endpoints, feature flags), not UI.

Testing. Mirror the package's own setup: Pest/PHPUnit with RefreshDatabase, a TestCase that boots the panel, and Livewire resource tests via livewire()->assertCanSeeTableRecords(). Run PHPStan at the package's level on your subclasses — since the package now gates CI on PHP 8.4 + PHPStan, type drift in your subclass signatures will surface as errors.

Gotchas and Tips

• The 5.9.0 refactor is the one thing that can break you. Models, resources, and login moved into user/admin packages. Expect changed namespaces. Grep your app for the old kit namespaces before upgrading, and remove any local User model, login page, or duplicated resource registration — two resources backed by the same model produce duplicate navigation entries and confusing 404s on detail pages.
• Migration collisions. If the previous version shipped a users/admins migration and the new packages ship their own, you will get "table already exists" on a fresh migrate. Either drop the old migration from your published set or gate it behind Schema::hasTable().
• Filament minor bumps need asset work. After composer update, run php artisan filament:upgrade, php artisan filament:assets, and php artisan optimize:clear. Stale published assets are the usual cause of "styles are broken after upgrade."
• Config cache bites. php artisan config:cache in deploy will freeze the published config. If panel behaviour changes only after config:clear, you are editing config that is cached.
• Discovery + package resources. With discovery enabled, an app-level resource extending a package resource can be registered twice. Either disable discovery for that panel or exclude the vendor path.
• Debugging a hidden resource: check in order — policy method, canViewAny(), panel ->resources([...]) list, shouldRegisterNavigation(), then permissions seeded. Filament gives no error for any of these.
• Tenancy. If you use Filament tenancy, the package resources need ->tenant(Team::class) and their models a team_id scope; the kit's resources are not tenancy-aware by default, so subclass and override getEloquentQuery().
• Extension points that are safe: the plugin class in PanelProvider, config keys, policy classes, resource subclasses, and navigation overrides. Unsafe: editing published vendor migrations in place (they get overwritten on re-publish), and overriding getPages() without also overriding the route names.
• CI parity. The release standardised workflows, dependabot, and PHPStan-on-8.4. Mirror that locally — run PHPStan and the test suite on 8.4 before bumping, and pin filament/filament to ^5.9 so a future Filament minor does not drag the kit outside its tested range.