Filament Companies Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require andrewdwallo/filament-companies
   php artisan filament-companies:install
   

   • Runs migrations, publishes config, and sets up Filament resources.

2. First Use Case

   • Visit /admin (Filament panel) to access the Companies and Employees resources.
   • Register a company admin via the /register route (auto-generated by the package).

3. Key Files to Review

   • config/filament-companies.php (core settings like default roles, email templates).
   • app/Providers/FilamentCompaniesServiceProvider.php (customization hooks).
   • database/migrations/ (check for custom tenant fields).

Implementation Patterns

Core Workflows

1. Company Tenancy

   • Multi-tenancy by default: Each company gets a dedicated database schema (if using spatie/laravel-multi-tenant).
   • Context switching: Use FilamentCompanies::setCurrentCompany($company) in middleware or services.
   • Example:

     use Andrewdwallo\FilamentCompanies\Facades\FilamentCompanies;
     
     // In a middleware:
     FilamentCompanies::setCurrentCompany(auth()->user()->company);
     

2. Employee Onboarding

   • Invite employees:

     $company->inviteEmployee('employee@example.com', ['role' => 'editor']);
     

   • Auto-accept invites: Configure in config/filament-companies.php:

     'auto_accept_invitations' => true,
     

3. Role-Based Access

   • Assign roles during invitation or via the Filament UI.
   • Check permissions in policies:

     public function viewAny(Company $company)
     {
         return auth()->user()->can('view companies');
     }
     

4. Socialite Integration

   • Configure providers in config/services.php (e.g., Google, GitHub).
   • Use the built-in SocialAuthController or extend:

     use Andrewdwallo\FilamentCompanies\Http\Controllers\SocialAuthController;
     
     Route::get('/login/google', [SocialAuthController::class, 'redirectToGoogle']);
     

5. Customizing Filament Resources

   • Extend resources via app/Filament/Resources/CompanyResource.php:

     namespace App\Filament\Resources;
     
     use Andrewdwallo\FilamentCompanies\Filament\Resources\CompanyResource as BaseCompanyResource;
     
     class CompanyResource extends BaseCompanyResource
     {
         public static function form(Form $form): Form
         {
             return parent::form($form)
                 ->schema([
                     // Add custom fields
                 ]);
         }
     }
     

Gotchas and Tips

Pitfalls

1. Database Schema Conflicts

   • If using spatie/laravel-multi-tenant, ensure the companies table has a schema_name column (or configure it in config/filament-companies.php).
   • Fix: Run php artisan vendor:publish --provider="Andrewdwallo\FilamentCompanies\FilamentCompaniesServiceProvider" to republish migrations.

2. Role/Permission Caching

   • Permissions may not update immediately if caching is enabled (e.g., spatie/laravel-permission).
   • Tip: Clear caches after role changes:

     php artisan cache:clear
     php artisan view:clear
     

3. Session Management Quirks

   • Company context is tied to the user’s session. Switching companies requires re-authentication.
   • Workaround: Use middleware to auto-switch:

     public function handle($request, Closure $next)
     {
         if (auth()->check()) {
             FilamentCompanies::setCurrentCompany(auth()->user()->company);
         }
         return $next($request);
     }
     

4. Email Templates

   • Customize templates in resources/views/vendor/filament-companies/emails/.
   • Note: Override the default invitation.blade.php for branded invites.

5. Sanctum vs. Session Auth

   • Sanctum tokens inherit the company context of the authenticated user. Ensure your API middleware respects this:

     use Andrewdwallo\FilamentCompanies\Facades\FilamentCompanies;
     
     public function handle($request, Closure $next)
     {
         if ($request->bearerToken()) {
             $user = auth()->user();
             FilamentCompanies::setCurrentCompany($user->company);
         }
         return $next($request);
     }
     

Debugging Tips

1. Log Company Context Add to AppServiceProvider:

   FilamentCompanies::macro('logContext', function () {
       \Log::info('Current Company:', [
           'id' => FilamentCompanies::getCurrentCompany()?->id,
           'name' => FilamentCompanies::getCurrentCompany()?->name,
       ]);
   });
   

2. Check Middleware Order Ensure FilamentCompanies\Middleware\SetCurrentCompany runs after auth middleware in app/Http/Kernel.php.

3. Invitation Debugging

   • Verify email queues are processing:

     php artisan queue:work
     

   • Check logs for failed invites:

     tail -f storage/logs/laravel.log | grep "Invitation"
     

Extension Points

1. Custom Invitation Logic Extend the EmployeeInvitation model:

   namespace App\Models;
   
   use Andrewdwallo\FilamentCompanies\Models\EmployeeInvitation as BaseInvitation;
   
   class EmployeeInvitation extends BaseInvitation
   {
       protected static function booted()
       {
           static::creating(function ($invitation) {
               // Add custom logic (e.g., log invites)
               \Log::info("New invite for {$invitation->email}");
           });
       }
   }
   

2. Webhook Events Listen for company/employee events:

   use Andrewdwallo\FilamentCompanies\Events\CompanyCreated;
   
   CompanyCreated::listen(function (CompanyCreated $event) {
       // Send Slack notification, etc.
   });
   

3. API Endpoints Add custom API routes in routes/api.php:

   use Andrewdwallo\FilamentCompanies\Http\Controllers\CompanyController;
   
   Route::middleware('auth:sanctum')->group(function () {
       Route::get('/companies/me', [CompanyController::class, 'current']);
   });