Filament Types Laravel Package

Getting Started

First Steps

1. Installation

   composer require tomatophp/filament-types
   

   Publish the config and migrations (if needed):

   php artisan vendor:publish --provider="TomatoPHP\FilamentTypes\FilamentTypesServiceProvider"
   php artisan migrate
   

2. Basic Setup Register the TypeResource in your app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->resources([
               // ... other resources
               \TomatoPHP\FilamentTypes\Resources\TypeResource::class,
           ]);
   }
   

3. First Use Case: Define a Custom Type Create a type model (e.g., app/Models/CustomType.php):

   use TomatoPHP\FilamentTypes\Contracts\Type;
   
   class CustomType implements Type
   {
       public static function getLabel(): string
       {
           return 'Custom Type';
       }
   
       public static function getSlug(): string
       {
           return 'custom_type';
       }
   }
   

   Register it in config/filament-types.php:

   'types' => [
       \App\Models\CustomType::class,
   ],
   

4. Access the Admin Panel Visit /admin/types to manage your custom type via Filament’s UI.

Implementation Patterns

Core Workflows

1. Defining Types

   • Implement the Type contract with getLabel() and getSlug().
   • Extend functionality via traits (e.g., HasFields, HasValidation):

     use TomatoPHP\FilamentTypes\Traits\HasFields;
     
     class CustomType implements Type
     {
         use HasFields;
     
         public static function getFields(): array
         {
             return [
                 \Filament\Forms\Components\TextInput::make('name')->required(),
             ];
         }
     }
     

2. Dynamic Field Management

   • Use getFields() to define form fields dynamically.
   • Leverage Filament’s components (e.g., Select, RichEditor) for rich UX:

     public static function getFields(): array
     {
         return [
             \Filament\Forms\Components\Select::make('status')
                 ->options(['active', 'inactive'])
                 ->required(),
         ];
     }
     

3. Validation and Logic

   • Add validation via getRules():

     use TomatoPHP\FilamentTypes\Traits\HasValidation;
     
     class CustomType implements Type
     {
         use HasValidation;
     
         public static function getRules(): array
         {
             return [
                 'name' => 'required|max:255',
             ];
         }
     }
     

4. Integration with Models

   • Attach types to Eloquent models via a morphTo relationship:

     // In your model (e.g., Post.php)
     public function type()
     {
         return $this->morphTo();
     }
     

   • Use the HasType trait for convenience:

     use TomatoPHP\FilamentTypes\Traits\HasType;
     
     class Post extends Model
     {
         use HasType;
     }
     

5. Customizing the Resource

   • Override the TypeResource class to modify behavior:

     namespace App\Filament\Resources;
     
     use TomatoPHP\FilamentTypes\Resources\TypeResource as BaseTypeResource;
     
     class CustomTypeResource extends BaseTypeResource
     {
         protected static ?string $model = \App\Models\CustomType::class;
     }
     

6. Bulk Actions and Filters

   • Extend the resource to add bulk actions or filters:

     public static function getPages(): array
     {
         return [
             'index' => Pages\ListTypes::route('/'),
             'create' => Pages\CreateType::route('/create'),
             // Add custom pages (e.g., for bulk actions)
             'bulk' => Pages\BulkActions::route('/bulk'),
         ];
     }
     

7. Handling Table Columns with Icons

   • New in v4.0.2: Ensure table columns with icons render correctly by providing a fallback or default icon:

     use Filament\Tables\Columns\IconColumn;
     
     public static function tableColumns(): array
     {
         return [
             IconColumn::make('icon')
                 ->boolean()
                 ->default(false) // Fallback for empty icons
                 ->label('Has Icon'),
         ];
     }
     

Gotchas and Tips

Common Pitfalls

1. Type Registration

   • Issue: Types not appearing in the admin panel.
   • Fix: Ensure the class is registered in config/filament-types.php under the types key.
   • Debug: Run php artisan config:clear if changes aren’t reflected.

2. Field Conflicts

   • Issue: Fields not rendering or validation errors.
   • Fix: Verify field names match the model’s fillable attributes. Use ->columnSpanFull() for complex layouts:

     TextInput::make('description')->columnSpanFull(),
     

3. Migration Conflicts

   • Issue: Database errors after publishing migrations.
   • Fix: Check for existing types table. Use php artisan migrate:fresh in development if needed.

4. Caching

   • Issue: Changes to types not reflecting immediately.
   • Fix: Clear Filament’s cache:

     php artisan filament:cache:clear
     

5. Permission Handling

   • Issue: Unauthorized access to type management.
   • Fix: Use Filament’s built-in policies or extend the TypeResource:

     protected static ?string $navigationIcon = 'heroicon-o-collection';
     protected static ?string $navigationGroup = 'Settings';
     protected static bool $shouldRegisterNavigation = true;
     

6. Table Icons in v4.0.2

   • Issue: Empty or missing icons in table columns.
   • Fix: Provide a default value or fallback icon for columns using IconColumn:

     IconColumn::make('icon')->default('heroicon-o-circle'),
     

Pro Tips

1. Reusable Type Logic

   • Create base types for common use cases (e.g., MediaType, UserRoleType) and extend them:

     class MediaType implements Type
     {
         use HasFields, HasValidation;
     
         public static function getFields(): array
         {
             return [
                 \Filament\Forms\Components\FileUpload::make('file')->image(),
             ];
         }
     }
     

2. Dynamic Type Selection

   • Use the type() relationship to dynamically fetch type-specific data:

     // In a Filament widget or page
     $type = $record->type;
     $fields = $type::getFields();
     

3. Localization

   • Localize type labels and fields:

     public static function getLabel(): string
     {
         return trans('types.custom_type.label');
     }
     

4. Testing

   • Test type management with Filament’s testing helpers:

     use TomatoPHP\FilamentTypes\Tests\CreatesTypes;
     
     class TypeTest extends TestCase
     {
         use CreatesTypes;
     
         /** @test */
         public function it_manages_custom_types()
         {
             $this->actingAsAdmin();
             $this->createType(\App\Models\CustomType::class, ['name' => 'Test']);
             $this->assertDatabaseHas('types', ['slug' => 'custom_type']);
         }
     }
     

5. Performance

   • Eager load relationships to avoid N+1 queries:

     $types = Type::with('model')->get();
     

   • Use defaultSort in the resource to optimize listing:

     protected static ?string $defaultSort = 'created_at desc';
     

6. Extending the Package

   • Add custom actions to the resource:

     public static function getBulkActions(): array
     {
         return [
             \TomatoPHP\FilamentTypes\Actions\ExportTypesAction::make(),
         ];
     }
     

   • Create custom widgets for type analytics:

     use TomatoPHP\FilamentTypes\Widgets\TypeStatsWidget;
     
     public static function getWidgets(): array
     {
         return [
             TypeStatsWidget::class,
         ];
     }