Basev3 Laravel Package

Getting Started

This release is almost entirely housekeeping — dependency bumps, CI workflow standardization, and a move from pnpm to bun for frontend assets. The one change that matters day-to-day is PR #92: "Use filament-user for the user model, resource and login", which changes where your User model and admin login come from.

Start here:

1. Confirm what you actually depend on. filakitphp/basev3 is a starter/base kit, not a typical runtime library. If you composer create-project fresh, you get the new wiring automatically. If you have an existing app scaffolded from an older base, nothing breaks until you next sync the skeleton — treat this as a template diff, not a composer update.
2. Check the User model wiring first. Open config/auth.php, app/Models/User.php, and the Filament panel provider. The filament-user package now supplies the model, the resource, and the login page. Verify your providers.users.model still points where you expect.
3. Re-run migrations and the admin login flow (/admin) before doing anything else. This is the fastest way to catch a mismatched user model.
4. Migrate asset tooling to bun if you were on pnpm (bun install, bun run build). The CI and lockfile expect bun now.
5. Verify the Filament version constraint resolves to ~3.3.56 and that your panel still boots — the bump is patch-level, so risk is low, but plugins with strict constraints can complain.

First real use case: scaffold a fresh project, log in as an admin, and confirm the generated User resource behaves as before. That validates the one behavioral change in this release.

Implementation Patterns

Treat the repo as a template, not a dependency. The most reliable workflow is to keep a diff between your app and the upstream skeleton, then cherry-pick. Blindly pulling 3.3.56 into an existing app will overwrite your User model with the filament-user version.

Extending the shipped user model. Rather than forking the vendor model, subclass or alias it:

// app/Models/User.php
namespace App\Models;

use FilamentUser\Models\User as BaseUser;

class User extends BaseUser
{
    // app-specific traits, casts, relations
}

Then point config/auth.php and the Filament panel's ->authGuard() / resource discovery at App\Models\User.

Panel configuration stays in the panel provider. Register the login page and user resource explicitly if you've swapped the model, so Filament doesn't resolve the vendor default:

->login(\Filament\User\Pages\Auth\Login::class)
->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')

Keep CI aligned with upstream. The standardized Dependabot config and update-changelog workflow are worth copying verbatim into your own repo — they're generic and save you reinventing them. PHPStan now runs on PHP 8.4, so add a phpstan.neon and run it in your pipeline before you upgrade PHP locally.

Group dependency updates. Upstream uses grouped Dependabot PRs (composer-deps, actions-deps, npm/bun). Mirror that grouping — it's the only reason this many bumps landed without churn.

Asset pipeline. Switch scripts to bun equivalents (bun run dev, bun run build) and delete pnpm-lock.yaml in the same commit as bun.lockb is added, never separately.

Gotchas and Tips

• The filament-user swap is the only breaking-ish change. It's not marked breaking, but any app that customized the previous User model, login page, or user resource will silently diverge. Diff app/Models/User.php, the login page reference, and the user resource before syncing.
• Auth provider mismatch is the classic failure. Symptom: login succeeds but the panel says unauthorized, or your relations disappear. Check config/auth.php → providers.users.model against the class the resource queries.
• Don't composer update a starter kit in production. Pin the skeleton by commit SHA and treat upgrades as reviewed PRs against your own repo.
• bun vs pnpm lockfiles. Shipping both confuses CI and IDE tooling. Commit the removal, and update any packageManager field in package.json.
• Filament patch bumps are usually safe, but plugin constraints aren't. If a third-party Filament plugin pins filament/filament: 3.3.55, composer will refuse the update. Run composer why-not filament/filament 3.3.56 to find the culprit.
• PHPStan on 8.4 can surface new deprecations in code that passed on 8.3. Expect a handful of nullsafe/implicit-nullable warnings; fix them before bumping your own runtime.
• Dependabot noise hides signal. With grouped updates this large, read the "Use filament-user…" and CI commits, skim the rest. Set up release-note filtering or you'll miss the next behavioral change the same way.
• Extension points to prefer: publish vendor config and views (php artisan vendor:publish --tag=filament-user-config) rather than editing vendor files, so future upstream changes merge cleanly.