Filament Form Builder Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tapp/filament-form-builder
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="TappNetwork\FilamentFormBuilder\FilamentFormBuilderServiceProvider"
   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \TappNetwork\FilamentFormBuilder\FilamentFormBuilderPlugin::make(),
           ]);
   }
   

3. First Form Creation

   • Navigate to Forms in the Filament admin panel.
   • Click "Create Form" and define:
     • Title (e.g., "Contact Us")
     • Fields (drag-and-drop Filament fields like TextInput, Select, etc.)
     • Validation Rules (Laravel-style, e.g., required|email).
   • Save and publish the form.

4. Frontend Usage Use the form Blade directive in your frontend view:

   @form('contact-us')
       @include('forms.contact-us')
   @endform
   

   Or via JavaScript:

   document.addEventListener('DOMContentLoaded', () => {
       const form = new FilamentFormBuilder.Form('contact-us');
       form.render('#form-container');
   });
   

Implementation Patterns

Core Workflows

1. Dynamic Form Building

   • Admin Panel: Use the Filament UI to assemble forms visually (no manual Blade templates needed).
   • Field Reusability: Leverage Filament’s existing fields (e.g., RichEditor, FileUpload) or extend with custom components.
   • Conditional Logic: Use visibleOn/requiredIf attributes in the admin panel to create dynamic forms.

2. Data Handling

   • Submission: Forms auto-generate a FormResponse model (extendable via php artisan make:filament-form-builder-model).
   • Validation: Rules are enforced server-side (Laravel) and client-side (via Filament’s built-in validation).
   • Storage: Responses are stored in the database by default; override with custom logic in the Form model’s saveResponse() method.

3. Frontend Integration

   • Blade Directives: Use @form('slug') for server-rendered forms.
   • JavaScript API: For SPAs or dynamic loading:

     FilamentFormBuilder.loadForm('contact-us', '#container').then(form => {
         form.on('submit', (data) => {
             console.log('Submitted:', data);
         });
     });
     

   • CSRF Protection: Automatically handled via Filament’s middleware.

4. Exporting Data

   • Use the Export button in the admin panel to generate CSV/Excel files:

     // Customize export columns in the Form model:
     protected static function getExportableColumns(): array
     {
         return [
             'name',
             'email',
             'created_at',
         ];
     }
     

5. Multi-Step Forms

   • Use the steps configuration in the admin panel to split forms into tabs/sections.
   • Access current step data via JavaScript:

     form.on('stepChange', (stepName) => {
         console.log('Current step:', stepName);
     });
     

Integration Tips

• Custom Fields: Extend FilamentFormBuilderField to create reusable components:

  namespace App\Filament\Forms\Fields;
  
  use TappNetwork\FilamentFormBuilder\Fields\FilamentFormBuilderField;
  
  class CustomField extends FilamentFormBuilderField
  {
      protected static ?string $view = 'filament-form-builder::fields.custom';
  }
  

• Webhooks: Trigger actions on submission via the Form model’s afterSave event:

  public static function booted()
  {
      static::afterSave(function ($model) {
          event(new FormSubmitted($model));
      });
  }
  

• Localization: Translate form labels/placeholders via Filament’s localization system:

  // In Form model:
  public static function getTranslatableAttributes(): array
  {
      return ['title', 'description'];
  }
  

Gotchas and Tips

Common Pitfalls

1. Field Serialization

   • Issue: Custom fields may not serialize correctly in the database.
   • Fix: Implement getState() and setState() in your custom field:

     public function getState(): array
     {
         return ['value' => $this->value];
     }
     
     public function setState(array $state): void
     {
         $this->value = $state['value'];
     }
     

2. Validation Overrides

   • Issue: Client-side validation (Filament) may not match server-side rules if not synced.
   • Fix: Use validation_rules in the admin panel or override the rules() method in your Form model:

     public function rules(): array
     {
         return [
             'email' => 'required|email|unique:form_responses,email',
         ];
     }
     

3. CSRF Token Mismatch

   • Issue: Frontend forms fail with "CSRF token mismatch" if the admin panel and frontend share the same session.
   • Fix: Use separate sessions or exclude the form routes from CSRF verification in VerifyCsrfToken middleware:

     protected $except = [
         'filament-form-builder/*',
     ];
     

4. Database Bloat

   • Issue: Storing all form responses may consume excessive space.
   • Fix: Implement soft deletes or archive old responses:

     // In FormResponse model:
     use Illuminate\Database\Eloquent\SoftDeletes;
     
     class FormResponse extends Model
     {
         use SoftDeletes;
         protected $dates = ['deleted_at'];
     }
     

5. JavaScript Conflicts

   • Issue: FormBuilder’s JS may conflict with other libraries (e.g., Alpine.js).
   • Fix: Load FormBuilder after other scripts or use a namespace:

     <script src="/vendor/filament-form-builder/js/form-builder.js" defer></script>
     

Debugging Tips

1. Log Form Data Add a FormSubmitted listener to inspect payloads:

   Form::afterSave(function ($model) {
       \Log::info('Form submitted:', $model->data);
   });
   

2. Check Field States Dump field states during form rendering:

   // In a custom field:
   public function mount(): void
   {
       \Log::debug('Field state:', $this->getState());
   }
   

3. Validate Admin Panel Config Ensure the config/filament-form-builder.php settings match your environment:

   'default_form_model' => \App\Models\Form::class,
   'default_response_model' => \App\Models\FormResponse::class,
   

4. Clear Cached Views If forms render incorrectly after updates:

   php artisan view:clear
   php artisan cache:clear
   

Extension Points

1. Custom Storage Override the saveResponse() method in your Form model to store data in a queue or external service:

   public function saveResponse(array $data): void
   {
       FormResponse::create([
           'form_id' => $this->id,
           'data' => $data,
       ]);
   
       // Send to external API
       Http::post('https://api.example.com/webhooks', $data);
   }
   

2. Field Presets Create reusable field configurations via FormField models:

   // app/Models/FormField.php
   public function getDefaultConfig(): array
   {
       return [
           'label' => 'Full Name',
           'field' => 'text_input',
           'required' => true,
       ];
   }
   

3. Frontend Theming Override Blade views in resources/views/vendor/filament-form-builder/ to customize styling:

   <!-- resources/views/vendor/filament-form-builder/forms/render.blade.php -->
   <div class="my-custom-form">
       @foreach($fields as $field)
           {!! $field->render() !!}
       @endforeach
   </div>
   

4. API Endpoints Expose form submissions via a custom API route:

   Route::post('/api/forms/{form}/submit', [FormController::class, 'submit'])->middleware('auth:sanctum');
   

   // In FormController:
   public function submit(Request $request, Form $form)
   {
       return $form->submit($request->all());
   }