Organizations Teams Filament Laravel Package

Getting Started

This is an optional Filament companion to a larger organizations/teams domain module — it ships admin UI (resources, relation managers, pages) rather than the domain model itself. Treat it as presentation-layer glue you mount into a panel, not as a standalone package.

Prerequisites to confirm before you install:

• The core teams/organizations domain package is already installed and migrated (this package almost certainly does not own those tables).
• Your Filament major version matches the package's composer.json constraint — with 0 stars and a single release, there is no community track record of version compatibility.
• You know which panel(s) should expose team admin: a central admin panel, a tenant panel, or both.

Minimal setup:

composer require liberusoftware/organizations-teams-filament

Then register the plugin in your panel provider:

use Liberu\Organizations\Teams\Filament\TeamsFilamentPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(TeamsFilamentPlugin::make());
}

Where to look first (in this order):

1. composer.json — Filament version constraint, extra.laravel.providers, and whether it declares any auto-discovered service provider.
2. src/*Plugin.php — the actual configuration surface. Whatever make() exposes is your extension API; everything else is internal.
3. src/Filament/Resources/** — the forms and tables. Read these before writing any custom resource; you will likely extend rather than replace.
4. config/ — if a config file is published, it usually controls navigation group, slugs, and which resources register.
5. README.md and tests/ — if tests exist, they are the only reliable documentation of intended behavior.

First use case: log in as a super-admin, confirm the Teams resource appears in navigation, create a team, attach a member, and verify the membership shows up on both the team detail page and the user's profile. That single loop exercises the form schema, the relation manager, and the policies — and will surface most integration problems immediately.

Implementation Patterns

Register per panel, not globally. Don't put the plugin in a shared base provider. Admin panels usually want full CRUD; tenant panels typically want scoped, read-mostly views. Two registrations with different configuration beats one registration with conditionals.

// Tenant panel
->plugin(
    TeamsFilamentPlugin::make()
        ->navigationGroup('Organization')
        ->tenantScoped() // verify the actual method name in the plugin class
)

Extend resources rather than forking. Point the plugin at your own resource class if it supports it; otherwise subclass and re-register. Overriding getFormSchema(), table(), and getPages() in a subclass keeps vendor updates mergeable. Never edit vendor/ — with one release and zero dependents, upstream will not preserve your patches.

Treat the plugin as a UI shell over domain actions. Keep business rules (seat limits, ownership transfer, invitation expiry) in the domain package's actions/services, and call them from custom Filament actions. If you let the admin UI write directly to pivot tables, you will diverge from whatever the API and console commands do.

Relation managers are the natural seam for membership. A TeamMembersRelationManager (or equivalent) is where roles, invitations, and removal live. Customize via ->form() and ->table() overrides, and gate destructive actions with policies rather than inline closures so the same rules apply to the API.

Authorization wiring. Confirm each resource's canViewAny, canCreate, and canDelete resolve through your TeamPolicy. In low-adoption packages these are frequently left permissive or hardcoded to true for convenience. If they are, override them in a subclass — do not assume the package ships secure defaults.

Multi-tenancy. If you use Filament's tenancy, verify the resource queries are scoped by tenant()/getEloquentQuery(). A team resource that ignores the current tenant will leak across organizations. Test with two tenants and a non-owner account before shipping.

Testing. Use Filament's Livewire helpers to assert resource behavior:

livewire(ListTeams::class)->assertCanSeeTableRecords($teams);
livewire(CreateTeam::class)->fillForm([...])->call('create')->assertHasNoFormErrors();

These tests are cheap insurance against a silent upstream change in a package with no other consumers validating it.

Gotchas and Tips

Zero stars, zero dependents is a real risk signal. Pin the exact version ("liberusoftware/organizations-teams-filament": "1.0.*") and read the source before upgrading. There is no Stack Overflow corpus for this package; the source is the documentation.

Filament major-version drift is the most likely breakage. Filament v3 → v4 renamed form/table APIs significantly (forms()/tables() replacing form()/table() in some contexts, schema namespace moves). Check the constraint, and if it is loose (^3.0), pin it in your root composer.json so a Composer update doesn't silently pull an incompatible Filament.

Navigation duplication. If the core organizations module also registers resources, you may see Teams twice. Fix by disabling one side (->shouldRegisterNavigation(false) on the resource, or a config flag) rather than hiding with CSS.

Migrations belong to the domain package. If this package publishes migrations, check for table-name collisions before running. Duplicate teams or team_user migrations are a common failure mode when optional modules overlap.

Cache aggressively, then clear aggressively. After changing panel configuration:

php artisan filament:optimize-clear
php artisan optimize:clear

Stale component caches produce "class not found" errors on resources that clearly exist.

Debugging policies and scoping. When a resource 403s or shows empty, check in this order: panel access (canAccessPanel), resource policy method, getEloquentQuery() scoping, then global scopes on the underlying model. Filament surfaces authorization failures as 403s with no detail.

Extension points to prefer, in order of durability: plugin configuration methods → resource subclassing → view overrides via ->view() → Livewire component replacement. Anything below that (trait conflicts, service container rebinding of internal classes) will break on the next release.

Budget for an exit. At this maturity level, keep your customizations concentrated in a handful of subclasses and a plugin registration block. If the package stalls, replacing it with two hand-written Filament resources should be a day's work, not a rewrite. Design for that.