Teamkitv5 Laravel Package

Getting Started

TeamKit v5 is a Laravel + Filament starter kit for apps that need multi-tenancy with a split user panel and admin panel. As of 5.9.0 it tracks Filament v5.9.0 and delegates the User/Admin models, resources and login screens to companion packages rather than shipping them inline — so the first thing to understand is which code lives in this repo vs. in jeffersongoncalves/* dependencies.

Minimal path:

1. Confirm your stack: PHP 8.2+, Laravel 11/12, Filament v5.x. The Filament bump to 5.9.0 means your other Filament plugins must also be v5-compatible.
2. Install into a fresh Laravel app (composer require jeffersongoncalves/teamkitv5), then run the published migrations and seeder. The seeder is what creates your first admin user — run it before trying to log in, or you'll get a 403 on /admin with no obvious error.
3. Look first at:
   • app/Providers/Filament/AdminPanelProvider.php and the user panel provider — panel IDs, paths, and ->tenant() config.
   • The TeamKit config file (team model, invitation behaviour, panel access rules).
   • The published migrations — especially the teams/pivot tables and any role columns.
4. First use case to exercise end-to-end: log into the admin panel, create a Team, attach a user, then log in as that user on the user panel and confirm tenant scoping works (you should only see that team's records, and the tenant switcher should appear if the user belongs to more than one team).

Implementation Patterns

Two panels, one codebase. Treat the admin and user panels as separate applications sharing models. Register resources per panel (AdminPanelProvider for oversight, user panel for tenant-scoped CRUD) rather than gating one resource with canAccess(). This keeps navigation clean and avoids leaking admin-only pages into tenant context.

Tenancy is the core abstraction. Resources that belong to a team should implement Filament's tenant-aware interfaces and rely on Filament::getTenant() for scoping. The reliable pattern:

• Team-owned resources: scope queries and auto-fill team_id on create.
• Truly global resources (e.g. plans, countries): don't make them tenant-aware; just hide them from the user panel.
• Cross-team admin views: put them on the admin panel where tenancy is off, or explicitly bypass scoping there.

Extend, don't edit vendor code. Since 5.9.0 the User/Admin models, resources and login pages come from packages. Subclass them in app/ and register the subclass (via panel ->login(YourLogin::class), ->model(), or the package's config swap) so composer update doesn't wipe your customisations. If you edited those files directly on 5.8.x, that work needs migrating into subclasses now.

Invitations / membership flow. Typical workflow: admin creates team → invites by email → invited user registers via the user panel → membership pivot row created with a role. Keep invitation acceptance in a dedicated action or controller, not inside the registration form, so you can reuse it for "add existing user to team".

Roles and access. Drive panel access from a single policy/canAccessPanel() implementation keyed off role, and reuse it in resource canViewAny()/canDelete() checks. One source of truth prevents the classic "user can see the button but the action 403s" mismatch.

Composition over a fork. For per-project behaviour, prefer Filament's hooks (->navigationGroups(), custom pages, Resource::getEloquentQuery() overrides in subclasses) plus small service classes. This package is a scaffold — most teams end up owning the resources within a few sprints.

Testing. The repo standardised its CI around a tests workflow in this release; mirror that locally with Pest/PHPUnit feature tests using actingAs($user) plus Filament::setTenant($team). Test both panels — the tenancy boundary is where regressions hide.

Gotchas and Tips

• 5.9.0 is an architectural shift, not just a dependency bump. PR #152 ("Use user/admin packages for models, resources and login") removes code you may have customised. Before upgrading from 5.8.x, diff your published app/Models/User.php, admin/user resources, and login pages against the packages, then move your changes into subclasses or a local override. Upgrade on a branch, not on main.
• Filament 5.9.0 alignment matters. Every Filament plugin in your composer.json (and any custom panel theme) must support v5. Mixed v4/v5 packages produce confusing "class not found" or "method does not exist" errors at panel boot, not at install time.
• Stale caches after the refactor. After upgrading, run php artisan filament:clear-cached-components, php artisan optimize:clear, and re-run php artisan filament:assets. Component caching will happily serve the old (now vendor-provided) resource classes.
• Migration ordering. If you already have a users table from a previous install, publishing the new package migrations can collide. Read each migration before running; prefer new dated migrations over editing existing ones.
• Missing admin login is usually a missing user. Post-refactor, the packages assume an admin-capable user exists. Check canAccessPanel() and the role column before assuming the login route is broken.
• Tenant scoping leaks. The two most common bugs: (1) a global scope applied on the admin panel hiding records admins should see, and (2) team_id not auto-filled because the resource's mutateFormDataBeforeCreate() wasn't overridden. Verify by creating a record as a non-super-admin in a second team.
• Panel path collisions. Default /admin and user panel slugs can clash with your app's existing routes; set explicit ->path() values and check php artisan route:list | grep -i admin.
• Debugging aids: php artisan about confirms the resolved Filament version; php artisan filament:optimize vs optimize:clear distinguishes "works in dev, breaks in prod" cache issues.
• Extension points to prefer: panel providers, the package's config swap keys for models/pages, resource subclasses, and Filament actions. Avoid editing vendor/ or relying on the demo seeder data in production.
• Watch the CI churn. This release is largely CI/dependabot standardisation (workflows, dependabot config, auto-merge). That's harmless for consumers but means the diff is noisy — filter to PR #152 and the dependency bumps when reviewing the upgrade.