Filateams Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laraveldaily/filateams
   php artisan migrate  # Runs FilaTeams migrations
   

   Ensure this is done before building Filament resources/pages.

2. User Model Update: Add traits to app/Models/User.php:

   use LaravelDaily\FilaTeams\Concerns\HasTeams;
   use LaravelDaily\FilaTeams\Concerns\HasTeamMembership;
   

3. First Use Case:

   • Log in as an admin (or create one via php artisan make:filament-user).
   • Navigate to Filament Panel → Teams tab (auto-registered).
   • Create a team, invite members, and assign roles (e.g., admin, member).

Key Files to Review

• Config: config/filateams.php (customize team defaults, roles, or branding).
• Resources: vendor/laraveldaily/filateams/src/Resources/ (extend via service providers).
• Migrations: database/migrations/.../create_teams_tables.php (if customizing schema).

Implementation Patterns

Core Workflows

1. Team Creation & Management:

   • Use the Teams Resource (/resources/filateams/team-resource.php) to customize fields (e.g., add description or logo).
   • Override the Team model (app/Models/Team.php) to add custom logic:

     class Team extends \LaravelDaily\FilaTeams\Models\Team
     {
         protected $fillable = ['custom_field'];
     }
     

2. Role-Based Access:

   • Assign roles via the Team Members tab in Filament.
   • Gate logic in policies:

     public function viewAny(Team $team): bool
     {
         return $team->members()->where('user_id', auth()->id())->exists();
     }
     

3. Tenancy Integration:

   • FilaTeams replaces Filament’s tenancy system. Use auth()->user()->currentTeam to access the active team in:
     • Resources: Filter queries by team:

       public static function getEloquentQuery(): Builder
       {
           return parent::getEloquentQuery()->where('team_id', auth()->user()->currentTeam->id);
       }
       

     • Pages: Dynamically switch teams via the Switch Team widget (auto-included).

4. Invitations:

   • Send invites via the Invite Members action in the Teams Resource.
   • Customize the invite email template by publishing views:

     php artisan vendor:publish --tag=filateams-views
     

     Then edit resources/views/vendor/filateams/emails/invite.blade.php.

Integration Tips

• Filament Widgets: Add the TeamSwitcher widget to your dashboard:

  use LaravelDaily\FilaTeams\Widgets\TeamSwitcher;
  
  public function getWidgets(): array
  {
      return [
          TeamSwitcher::class,
      ];
  }
  

• Middleware: Protect routes by team:

  Route::middleware(['auth', 'team'])->group(function () {
      // Team-restricted routes
  });
  

• APIs: Expose team data via Filament’s API:

  public static function getApiResource(): ?string
  {
      return \LaravelDaily\FilaTeams\Http\Resources\TeamResource::class;
  }
  

Gotchas and Tips

Pitfalls

1. Migration Order:

   • Run php artisan migrate after installing FilaTeams but before creating custom migrations that might conflict with its tables (teams, team_memberships, etc.).

2. Tenancy Conflicts:

   • If using Stancl/Avenger, disable it or merge configurations:

     'tenancy' => [
         'driver' => 'filateams', // Override Stancl's driver
     ],
     

   • FilaTeams overwrites Filament’s tenancy system. Avoid mixing both.

3. Role Permissions:

   • Default roles (admin, member) are hardcoded. To add custom roles:
     • Extend the TeamRole model:

       class TeamRole extends \LaravelDaily\FilaTeams\Models\TeamRole
       {
           protected static array $customRoles = ['editor'];
       }
       

     • Update the config:

       'roles' => [
           'admin', 'member', 'editor', // Add custom roles
       ],
       

4. Team Switching:

   • The currentTeam relation is cached. Clear it manually if needed:

     auth()->user()->currentTeam->refresh();
     

   • Avoid race conditions when switching teams in real-time apps by using:

     event(new \LaravelDaily\FilaTeams\Events\TeamSwitched);
     

Debugging

• Logs: Enable debug mode in config/filateams.php:

  'debug' => env('FILATEAMS_DEBUG', false),
  

• Queries: Use DB::enableQueryLog() to inspect team-related queries.
• Seeding: Reset teams with:

  php artisan db:seed --class=FilaTeamsDatabaseSeeder
  

Extension Points

1. Custom Fields:

   • Add fields to the Team model and sync with the Resource:

     public static function form(Form $form): Form
     {
         return $form
             ->schema([
                 // ... existing fields
                 TextInput::make('custom_field')->required(),
             ]);
     }
     

2. Webhooks:

   • Listen for team events (e.g., TeamCreated):

     use LaravelDaily\FilaTeams\Events\TeamCreated;
     
     public function boot()
     {
         event(TeamCreated::class, function (TeamCreated $event) {
             // Send Slack notification, etc.
         });
     }
     

3. UI Customization:

   • Publish and override views:

     php artisan vendor:publish --tag=filateams-views
     

   • Modify resources/views/vendor/filateams/partials/team-switcher.blade.php to change the UI.

4. API Extensions:

   • Extend the API resource:

     class CustomTeamResource extends \LaravelDaily\FilaTeams\Http\Resources\TeamResource
     {
         public function toArray($request): array
         {
             return array_merge(parent::toArray($request), [
                 'custom_field' => $this->custom_field,
             ]);
         }
     }
     

     Then bind it in AppServiceProvider:

     \LaravelDaily\FilaTeams\Http\Resources\TeamResource::macro('custom', fn () => CustomTeamResource::class);