Filament Field Group Laravel Package

## Getting Started

### First Steps
1. **Installation**:
   ```bash
   composer require solution-forest/filament-field-group
   php artisan filament-field-group:install

Register the plugin in your PanelProvider:

use SolutionForest\FilamentFieldGroup\FilamentFieldGroupPlugin;

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

2. Enable the Plugin:

   • Set 'enabled' => true in config/filament-field-group.php or use ->enablePlugin() in your PanelProvider.

3. First Use Case:

   • Navigate to the Field Group resource in Filament.
   • Create a new Field Group (e.g., "User Profile").
   • Add fields (e.g., Text, Email, Toggle) to the group.
   • Reference the group in your form schema:

     use SolutionForest\FilamentFieldGroup\Facades\FilamentFieldGroup;
     
     public static function form(Form $form): Form {
         return $form->schema([
             FilamentFieldGroup::findFieldGroup('user_profile'),
         ]);
     }
     

Implementation Patterns

Core Workflow

1. Define Groups:

   • Use the Field Group resource to create reusable field collections (e.g., "Billing Info," "User Preferences").
   • Example: Group name, email, and phone under "Contact Details."

2. Reuse Groups in Forms:

   • Dynamically include groups in any Filament form:

     $form->schema([
         FilamentFieldGroup::findFieldGroup('contact_details'),
         FilamentFieldGroup::findFieldGroup('billing_info'),
     ]);
     

3. Conditional Rendering:

   • Use the statePath config to dynamically show/hide groups based on form state:

     FilamentFieldGroup::findFieldGroup('advanced_options')
         ->statePath('show_advanced')
     

4. Nested Groups:

   • Create hierarchical groups (e.g., "User" → "Profile" → "Address") for complex forms.

Advanced Patterns

1. Custom Field Types:

   • Extend existing types (e.g., add a RichText field):

     class RichTextField extends FieldTypeBaseConfig {
         public function getFormSchema(): array {
             return [
                 RichEditor::make('content')->columnSpanFull(),
             ];
         }
     }
     

   • Register via FilamentFieldGroupPlugin::make()->fieldTypeConfigs([RichTextField::class]).

2. Dynamic Group Loading:

   • Fetch groups based on user roles or permissions:

     if (auth()->user()->can('edit_advanced')) {
         $form->schema([FilamentFieldGroup::findFieldGroup('admin_settings')]);
     }
     

3. State-Dependent Logic:

   • Use configureFieldTypeConfigFormUsing to add dynamic options:

     FilamentFieldGroup::configureFieldTypeConfigFormUsing(
         Text::class,
         fn ($field, $schema) => array_merge($schema, [
             Toggle::make('required')->default(false),
         ])
     );
     

4. Resource Overrides:

   • Replace default resources (e.g., customize the Field Group CRUD):

     $panel->plugin(FilamentFieldGroupPlugin::make()->resources([
         CustomFieldGroupResource::class,
     ], override: true));
     

Gotchas and Tips

Common Pitfalls

1. Field Group Not Found:

   • Ensure the group name matches exactly (case-sensitive) and the config 'enabled' => true.
   • Debug with:

     dd(FilamentFieldGroup::findFieldGroup('group_name')); // Returns null if not found.
     

2. State Path Mismatches:

   • Verify statePath values in groups match the form’s state array keys.
   • Example: If statePath('is_active') is set, ensure the form tracks is_active.

3. Caching Issues:

   • Clear Filament’s view cache after adding custom field types:

     php artisan filament:cache-reset
     

4. Migration Conflicts:

   • If publishing migrations, check for table name collisions in config/filament-field-group.php:

     'table_names' => [
         'fields' => 'custom_advanced_fields',
         'field_groups' => 'custom_advanced_field_groups',
     ],
     

Pro Tips

1. Reusable Configs:

   • Store group IDs in constants or config files to avoid magic strings:

     // config/filament-field-groups.php
     return [
         'user_profile' => 'user_profile_group',
         'billing' => 'billing_group',
     ];
     

     Usage:

     FilamentFieldGroup::findFieldGroup(config('filament-field-groups.user_profile'));
     

2. Validation Rules:

   • Add validation via mixins:

     class RequiredMixin {
         public function addRequiredRule() {
             return fn () => ['required'];
         }
     }
     Text::mixin(new RequiredMixin());
     

3. Performance:

   • Eager-load groups in forms to reduce database queries:

     FilamentFieldGroup::findFieldGroup('group_name')->eagerLoadFields();
     

4. Testing:

   • Mock the facade for unit tests:

     FilamentFieldGroup::shouldReceive('findFieldGroup')
         ->once()
         ->andReturn(FakeFieldGroup::new());
     

5. Debugging:

   • Dump group schema to inspect fields:

     dd(FilamentFieldGroup::findFieldGroup('group_name')->getFormSchema());
     

6. Localization:

   • Publish translations for custom field types:

     php artisan vendor:publish --tag="filament-field-group-translations"
     

7. Filament 5+ Compatibility:

   • Use FilamentFieldGroup::make() (v3+) for newer Filament versions:

     FilamentFieldGroup::make()->schema([...])->statePath('dynamic_key');
     

---