Teamkitv4 Laravel Package

Getting Started

teamkitv4 is a Laravel + Filament v4 application kit (not a drop-in library): you scaffold a project from it, then own the code. Treat it as a starting point, not a dependency you upgrade blindly.

1. Install / scaffold

   composer create-project jeffersongoncalves/teamkitv4 my-app
   cd my-app
   cp .env.example .env && php artisan key:generate
   

   If you're adding it to an existing app instead, composer require jeffersongoncalves/teamkitv4 and check the README for the service provider / panel provider registration — with 4.14.0 the user/admin surface moved into separate sibling packages, so the install set may now be more than one require.

2. Database and assets

   php artisan migrate --seed
   php artisan filament:assets
   php artisan storage:link
   

   Seeders create the initial admin account — check database/seeders/ for the credentials before you try to log in.

3. Where to look first

   • app/Providers/Filament/*PanelProvider.php — panel IDs, paths, tenancy, auth guard, colors, middleware. This is the control panel for everything.
   • app/Models/ — User, Team, membership/pivot models, and (as of 4.14.0) Admin if the split user/admin packages are wired in.
   • app/Filament/ — Resources, Pages, Widgets per panel.
   • app/Policies/ and config/permission.php — who can see what.
   • config/teamkit* / config/filament* — anything package-published.

4. First real use case: log in as admin → create a Team → invite/attach a User → confirm the user sees only their team's records. That single loop exercises tenancy, policies, panels, and the seeded roles at once. If that loop works, the rest of the kit is just CRUD you can pattern-match.

Implementation Patterns

Two-panel pattern (admin vs. user). The kit ships (or, from 4.14.0, delegates to the user/admin packages) a separate admin panel and user panel. Keep them isolated: distinct panel IDs (admin, app), distinct path prefixes, and distinct guards if you need different session cookies. Share models, not panel config.

// app/Providers/Filament/AdminPanelProvider.php
->id('admin')
->path('admin')
->login()
->authGuard('web')          // or a dedicated 'admin' guard
->tenant(Team::class)       // omit for a global admin panel
->discoverResources(in: app_path('Filament/Admin/Resources'), for: 'App\\Filament\\Admin\\Resources')

Team tenancy. Let Filament do the scoping rather than hand-rolling where('team_id', ...). Implement Filament\Models\Contracts\HasTenants on User, register ->tenant(Team::class), and then every tenant-aware Resource is automatically filtered. In Resources, add ->tenantOwnershipRelationshipName('team') where the relationship name differs.

Extend, don't edit vendor code. If models/resources come from the user/admin packages in 4.14.0+, subclass them in app/ and repoint the container/config rather than patching vendor/. Publish only what you must:

php artisan vendor:publish --tag=teamkit-config
php artisan vendor:publish --tag=teamkit-migrations

Anything you don't publish becomes an upgrade liability.

Resource workflow. Scaffold with php artisan make:filament-resource Invoice --generate --view, then immediately tighten: ->navigationGroup(), ->recordTitleAttribute(), and form/table authorization via policies. Filament will silently show create/edit buttons the user can't use unless the policy methods (create, update, delete, viewAny) exist and are correct.

Role checks in one place. Wrap role logic in a HasTeamRoles trait or Gate::before so both panels and policies agree. Avoid sprinkling $user->hasRole(...) through Blade and Resources.

Testing. Pest/PHPUnit with Livewire::test(TeamResource\Pages\CreateTeam::class) for panel flows, plus plain feature tests for policies. Use actingAs($user) and assert against the panel's tenant context — plain HTTP tests won't catch tenancy leaks.

Gotchas and Tips

• 4.14.0 is a namespace-moving release. "Use user/admin packages for models, resources and login" means classes that previously lived in App\Models\User / App\Filament\Resources\... may now be supplied by a package. Before upgrading, grep for fully-qualified references (policies in AuthServiceProvider, ->model(), getModel(), factory imports, config/auth.php providers). Pin the old version if you have customisations layered on those classes.
• Filament minor bumps are not always minor. 4.14.0 bundles a Filament version bump; Filament v4.x has shipped API shuffles in ->form(), schema/table namespaces, and action classes. Skim the Filament changelog for your span, not just the kit's.
• Rebuild assets after every upgrade: php artisan filament:assets && php artisan optimize:clear. Stale CSS/JS after a panel or theme change produces "looks broken but code is fine" bugs.
• Tenancy leaks are silent. A Resource that forgets ->tenant() still renders — it just shows every team's rows. Add a test asserting team A can't see team B's records; do it early, because it's the failure mode you'll never spot in a demo.
• Seeder credentials drift. The seeded admin password comes from env (ADMIN_EMAIL/ADMIN_PASSWORD) or a hardcoded default. On a fresh clone with an old cached config you'll get "invalid credentials" and chase the wrong problem. php artisan config:clear first.
• Policy auto-discovery only works for App\Models. Models moved into vendor packages in this release won't auto-resolve App\Policies\UserPolicy — register explicitly in AuthServiceProvider/Gate::policy().
• Panel middleware order matters. Authenticate before tenancy middleware; otherwise authGuard mismatches surface as a 403 inside the panel rather than a redirect to login.
• Dependabot noise in the release notes is a signal, not a distractor. This release's substance is the CI standardization and the user/admin split; the dependency bumps are mostly tooling. Don't infer a feature set from the changelog's length.
• Extension points worth knowing: Filament\Panel::plugin(), custom Resource base classes in app/Filament/Resources/Resource.php, Filament::registerRenderHook(), and the kit's own config files. Prefer these over editing generated resources, which will be overwritten by the next make:filament-resource --generate.