Basev4 Laravel Package

Getting Started

This is a Filament v4 starter kit (filakitphp/basev4), not a drop-in library. The fastest path is to scaffold a new project rather than composer require it into an existing app:

composer create-project filakit/basev4 my-app
cd my-app
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
pnpm install && pnpm build
php artisan serve

Log in at /admin. Look first at:

• app/Providers/Filament/ — panel configuration (path, auth guard, colors, middleware).
• app/Filament/ — resources, pages, and widgets to copy as patterns.
• app/Models/User.php and config/filament-user.php — as of 4.14.0 the user model, user resource, and login flow come from the filament-user package (PR #111), so authentication customization starts there, not in the starter's own files.
• composer.json / package.json — confirm Filament is pinned to ^4.14 and the frontend uses pnpm (the bun migration in #112 was reverted in #113).

First use case: scaffold one CRUD resource (php artisan make:filament-resource Post --generate) and compare it against the kit's conventions for forms, tables, and policies.

Implementation Patterns

Panel-first development. Treat the generated panel provider as the source of truth. Register resources, pages, and widgets there; add middleware (e.g. AuthenticateSession, locale switching) at the panel level rather than per-resource.

Resource workflow.

php artisan make:filament-resource Customer --generate --view
php artisan make:filament-page Settings
php artisan make:filament-widget StatsOverview --stats
php artisan make:policy CustomerPolicy --model=Customer

Keep form/table schemas in the resource class until they grow; then extract to dedicated schema classes and reference them from both resource and relation managers.

Auth and user management. Since 4.14.0, lean on filament-user for the User model, user resource, and login. Customize by publishing its config/migrations/views rather than editing vendor files. If your app already has a User model, alias or extend the package model and point config/auth.php and the panel's ->authGuard() at it consistently.

Frontend assets. Use pnpm end-to-end (pnpm install, pnpm dev, pnpm build). The release history shows a bun experiment that was reverted; matching CI means committing pnpm-lock.yaml and not bun.lockb. Custom Filament themes go through a Vite entry registered in the panel provider with ->viteTheme().

Testing. Filament v4 works well with Pest/Livewire tests. Use Livewire::test(ManagePosts::class) and actingAs($user) with the same guard as the panel; seed roles/permissions in a test seeder so policy checks are exercised.

Upstream tracking. This is opinionated scaffolding. Keep a branch or tag noting the upstream version, and cherry-pick changes (e.g. the filament-user migration) rather than blind-merging main.

Gotchas and Tips

• 4.14.0 is a Filament version bump, not a starter-kit rewrite. Run composer update "filament/*" and then php artisan filament:upgrade && php artisan filament:assets. Filament minor releases occasionally move classes; if you see “class not found” after upgrading, check imports against the v4 namespace layout (schemas/actions were reorganized from v3).
• The user-model swap (#111) is the real behavioral change. Existing installations that customized app/Models/User.php, the users migration, or login pages should diff against filament-user before upgrading. Common breakages: extra user columns not present in the package migration, custom getFilamentName()/avatar methods, and password broker or guard mismatches.
• Don’t mix package managers. CI runs PHPStan on PHP 8.4 and uses pnpm after the bun revert. Reintroducing bun locally will produce lockfile noise and asset drift in CI.
• PHP 8.4 + PHPStan. Newer static analysis is stricter; keep phpstan.neon aligned with the kit and run vendor/bin/phpstan analyse before pushing, especially after adding custom Filament pages with dynamic schemas.
• Starter kit ≠ upgradable dependency. Pulling filakit/basev4 into an existing Laravel app will overwrite providers, routes, and config. Port patterns manually, or start from the kit and migrate your domain code in.
• Config caching bites Filament panels. After changing panel providers or config/filament*.php, run php artisan optimize:clear; stale caches are a frequent cause of “panel not found” and missing assets.
• Seeded demo data is not production data. Replace the default seeder and demo credentials before any deployment; also review APP_ENV, APP_DEBUG, and the panel’s ->domain()/path settings in production.
• Extension points: publish Filament config/assets (vendor:publish --tag=filament-config, filament-assets), publish filament-user resources/views, and register custom render hooks or middleware in the panel provider rather than patching vendor code.