Kaido Kit Laravel Package

Getting Started

Kaido Kit is a starter kit, not a runtime dependency — the first move is to scaffold a new project from it, not composer require it into an existing one.

1. Clone or use the repo as a template (git clone then composer install, or GitHub's "Use this template"), then copy .env.example → .env and run php artisan key:generate.
2. Run the installer: php artisan migrate --seed (Kaido ships with seeders that create the first admin user and role scaffolding). Check database/seeders/ and the README for the default credentials before running — they're usually [email protected] / password.
3. Boot the panels: php artisan serve and hit /admin. If using the multi-panel setup, also check /app or any other registered panel provider under app/Providers/Filament/.
4. Where to look first:
   • app/Providers/Filament/*PanelProvider.php — panel paths, colors, auth guards, navigation groups.
   • app/Filament/Resources/ — the shipped resources (Users, Roles, maybe Settings) are your templates.
   • config/filament-shield.php and config/permission.php — if role management is present.
   • composer.json — note the Filament major version; it dictates the API you'll use everywhere.

First use case: log in as the seeded admin, open the Users resource, create a user, assign a role, and confirm the new user sees the correct navigation. That one loop exercises auth, policies, resources, and Shield together — if it works, the base is healthy.

Implementation Patterns

Model + Resource pairing is the workflow. For every new domain entity, generate the Filament resource first (php artisan make:filament-resource Invoice --generate) and let it scaffold the form/table, then edit. Don't hand-roll resources; the generated stubs match the kit's conventions (navigation groups, getNavigationGroup(), icons).

Custom pages vs. resources. Use a Resource when CRUD maps to an Eloquent model. Reach for a custom Filament Page (make:filament-page) for dashboards, wizards, or settings screens, and bind them via the panel provider's ->pages([...]). Kaido's shipped pages show the pattern.

Policies over role checks in resources. Since Shield wires can() into resources, register policies (php artisan make:policy InvoicePolicy --model=Invoice) and let Filament enforce them. Resist inline auth()->user()->hasRole('admin') inside resource methods — it breaks Shield's caching and the permission UI.

Multi-panel isolation. If the kit ships separate AdminPanelProvider and AppPanelProvider, keep resources in the panel that owns them. Shared models are fine; shared resources usually aren't — duplicate and scope with canAccessPanel() on the User model.

Widgets as the dashboard layer. Stats/Chart widgets (make:filament-widget) are the idiomatic way to surface aggregates; register them in the panel provider or override getWidgets().

Integrate via service classes, not resource closures. When a form action needs business logic (invoice generation, notifications), call a service or action class from the Filament action closure. Keeps the resource testable and reusable from queues/commands.

Seeders as fixtures. Add a seeder per feature (roles, demo data) so migrate:fresh --seed gets a working dev environment in one command. This is the highest-leverage habit with a starter kit.

Gotchas and Tips

• Starter kit ≠ upgradeable package. Once cloned, you own the code. Bug fixes in upstream Kaido won't reach you. Treat the initial commit as your baseline and diff selectively.
• Filament major-version drift. If you upgrade Filament (v3 → v4), expect resource stubs, form APIs, and the Shield package to break in tandem. Pin Filament and filament-shield together; check their upgrade guides before touching either.
• Shield permission cache. After adding a resource or permission, run php artisan shield:generate --all and clear caches (php artisan permission:cache-reset / optimize:clear). A "permission denied" after a working change is almost always a stale cache.
• canAccessPanel() on User. New users silently can't log in if this method denies them by role. First debugging step for "valid credentials, still 403."
• Panel path collisions. If both panels default to /admin, only one registers. Verify ->path() in each provider.
• Navigation ordering surprises. $navigationSort and group ordering interact unpredictably when groups are declared in multiple providers — centralize group definitions or use constants.
• Seed credentials in production. Strip the demo seeder and default password before any deploy; the kit ships with known credentials by design.
• Livewire asset publishing. After composer update, php artisan filament:assets (or vendor:publish) is often needed for CSS/theme changes to appear.
• Extension points worth knowing: panel ->colors(), ->brandLogo(), ->darkMode(), ->tenant() for multi-tenancy; Filament::registerNavigationGroups() for global grouping; custom themes via php artisan make:filament-theme if using Filament v3.
• Debugging blank panels: check storage/logs/laravel.log first, then run php artisan about — panel provider registration errors surface there faster than in the browser.
• Testing: Filament ships Livewire test helpers (livewire(UserResource\Pages\CreateUser::class)->fillForm(...)->call('create')); use them rather than browser tests for resource coverage.

Overall this is a high-velocity starting point, low long-term maintenance story — great for greenfield admin panels where you want Users/Roles/Settings on day one, less suited to teams that expect to pull upstream updates. Budget a day to clone, audit the shipped resources, and strip anything you won't use before you build on top of it.