Mfakitv5 Laravel Package

Getting Started

This release (5.9.0) is a maintenance + architecture release: it bumps the Filament dependency to v5.9.0, standardizes CI, and — most importantly for day-to-day work — moves models, resources and login into dedicated user and admin packages (PR #79). Start there.

1. Install / upgrade

   composer require jeffersongoncalves/mfakitv5:^5.9
   php artisan vendor:publish --tag="mfakitv5-config"
   php artisan vendor:publish --tag="mfakitv5-migrations"
   php artisan migrate
   

   If you are coming from 5.8.x, run composer update "jeffersongoncalves/mfakitv5" -W and then php artisan filament:upgrade plus php artisan optimize:clear; the package split changes namespaces, so an upgrade is not a drop-in composer update.

2. Where to look first

   • The panel provider(s) registered by the package (AdminPanelProvider / user panel provider) — this is what decides routes, auth guard, and which resources appear where.
   • The admin package: your Filament Resources, Pages, Widgets.
   • The user package: the User model, auth/login page, and any profile-related resources.
   • config/filament.php and the package config for panel paths, guards, and middleware.

3. First use case — log in and scaffold one resource:

   php artisan make:filament-user        # create the first admin
   php artisan make:filament-resource Post --generate
   

   Then hit /admin and confirm the resource shows up under the admin panel. If it does not, the resource was generated into the wrong namespace for the new package layout.

Implementation Patterns

Two-package layout (the headline change in 5.9.0). Treat the split as a boundary, not a folder rename:

• User package — owns the User model, authentication, registration/profile pages, and anything a non-admin needs. Keep your app-level App\Models\User extending (or aliasing) the package model rather than duplicating it.
• Admin package — owns Filament panel providers, Resources, Pages, Widgets, and policy registration. Admin-only concerns stay here so the user side can ship without pulling in admin UI.

Resource scaffolding into the right namespace. When generating, point the generator at the admin package explicitly rather than relying on the default app/Filament location, otherwise you get resources that live in the app but are registered against a panel that expects package-namespaced classes. Verify the generated class appears in the panel's discoverResources() path.

Panel separation. If your app has both an admin panel and an end-user panel, register them as two providers with distinct ->id(), ->path(), and ->authGuard(). Cross-wiring the guard is the most common way a login page silently redirects to the wrong panel. Use ->login() on exactly one provider per guard.

Auth wiring. Because login moved into the user package in this release, any custom login customization you had (custom Login page, extra form fields, 2FA) should now be implemented in the user package's login class or overridden via the panel provider's ->login(YourLogin::class), not by editing vendor code.

Test and static-analysis parity. CI now runs PHPStan on PHP 8.4 and standardizes the test matrix across the board. Mirror that locally: run PHPStan (and Pint) against your own resources after scaffolding — package-level namespace changes are exactly where type errors surface, and the package's CI passing does not mean your overrides still typecheck.

Integration tip. Pin the Filament constraint you actually develop against and keep the starter kit in lockstep — the kit follows Filament minor releases closely (this release aligns with Filament v5.9.0), so a mid-cycle Filament bump in your own composer.json is the usual source of "works in the kit, breaks in my app."

Gotchas and Tips

• Upgrading from 5.8.x requires namespace work. PR #79 relocated models, resources and login. Run composer dump-autoload, then grep your codebase for the old namespaces before assuming a failed class is a bug.
• Clear everything after upgrading. php artisan optimize:clear && php artisan filament:upgrade && composer dump-autoload. Stale panel/resource caches make it look like the package split broke discovery when it didn't.
• Dependabot noise is normal here. Much of 5.9.0 is dependabot bumps plus CI standardization (workflows, dependabot config, auto-merge for actions). Don't infer app-facing changes from the bump list — the only real behavioural change is the user/admin package split. The vite bump is dev-tooling only.
• Debugging resource discovery. If a resource vanishes, check in this order: (1) correct namespace for the package it lives in, (2) discoverResources() path in the panel provider, (3) policy registration still pointing at the old model class, (4) cache cleared.
• Extension points rather than edits. Override via the panel provider (->login(), ->brandName(), ->discoverResources()), config publishing, or subclassing the package's resources/pages. Editing inside vendor/jeffersongoncalves/mfakitv5 will be lost on the next minor release — and this package cuts minors frequently.
• PHP 8.4 is now exercised in CI (PHPStan on 8.4). If you run 8.3 you're fine, but 8.4-specific deprecations in your resources won't be caught by the package's checks — run your own static analysis.
• Auth guard mismatch. After the split, confirm the User model in the user package is the same class configured in config/auth.php and in the panel's authGuard(). Two copies of a User model is the quiet path to "logged in but unauthorized."
• Read the diff for 5.9.0 in one pass. The changelog is CI-heavy; the substantive change is a single PR. Skim PR #79's file list rather than the whole compare — it tells you exactly which namespaces moved.