Livewire Form Builder Laravel Package

Getting Started

Minimal Steps to First Use Case

1. Installation

   composer require tivents/livewire-form-builder
   php artisan vendor:publish --tag=livewire-form-builder-config
   php artisan livewire-form-builder:publish-stubs
   

   • Verify config/livewire-form-builder.php and app/Repositories/FormRepository.php are published.

2. Define a Form Create a form definition in a Livewire component:

   use Tivents\LivewireFormBuilder\Contracts\FormRepositoryContract;
   use Tivents\LivewireFormBuilder\Components\FormBuilder;
   
   public function mount(FormRepositoryContract $formRepository) {
       $this->form = $formRepository->getForm('contact_form');
   }
   
   public function render() {
       return view('livewire.form-builder', [
           'form' => $this->form,
       ]);
   }
   

3. Create a Form via UI

   • Visit /form-builder (route defined in routes/web.php after publishing).
   • Drag-and-drop fields (e.g., text, email, submit) onto the canvas.
   • Save the form (stored in database/forms table by default).

4. Render the Form Use the FormBuilder component in a Blade view:

   <livewire:form-builder :form="$form" />
   

5. Handle Submissions Implement FormRepositoryContract to process submissions:

   public function storeSubmission(array $data) {
       // Save to your model (e.g., Contact::create($data))
   }
   

Implementation Patterns

Core Workflows

1. Form Design

   • Drag-and-Drop UI: Use the /form-builder route to visually design forms.
   • Field Configuration: Set labels, validation rules, and conditional logic directly in the UI.
   • Multi-Column Layouts: Use row fields to create responsive grids (e.g., 1/2 columns for side-by-side fields).

2. Dynamic Form Rendering

   • Livewire Component Integration:

     <livewire:form-builder
         :form="$form"
         wire:model="submissionData"
         @submitted="handleSubmission"
     />
     

   • Real-Time Validation: Validation rules (e.g., required|email) are applied per-field without manual JS.

3. Conditional Logic

   • Define rules in the UI (e.g., "Show phone field if country is 'US'").
   • Logic is rendered as client-side JS via Livewire’s wire:ignore and Alpine.js.

4. Submission Handling

   • Repository Pattern: Extend FormRepository to map submissions to your models:

     public function storeSubmission(array $data) {
         YourModel::create($this->mapData($data));
     }
     

   • CSV Export: Trigger via:

     $this->form->exportSubmissionsToCsv();
     

5. Repeater Groups

   • Add a repeater field to create dynamic nested forms.
   • Configure nested columns/fields within the repeater UI.

Integration Tips

• Custom Fields: Extend the field types by publishing and overriding the resources/views/vendor/livewire-form-builder/fields directory.
• Authentication: Restrict access to /form-builder via middleware:

  Route::middleware(['auth'])->group(function () {
      Route::get('/form-builder', [FormBuilderController::class, 'index']);
  });
  

• Form Templates: Use JSON schema import/export to share form definitions across projects:

  $form->exportToJson(); // Save to storage
  FormRepository::importFromJson($json);
  

Gotchas and Tips

Pitfalls

1. Repository Contract Misalignment

   • Issue: Forgetting to implement FormRepositoryContract methods (e.g., getForm, storeSubmission).
   • Fix: Run php artisan livewire-form-builder:publish-stubs and extend the stubbed FormRepository:

     class FormRepository implements FormRepositoryContract {
         public function getForm(string $formId) { ... }
         public function storeSubmission(array $data) { ... }
     }
     

2. Conditional Logic Not Updating

   • Issue: Conditional fields fail to show/hide dynamically.
   • Fix: Ensure the wire:key is unique for conditional fields and that Alpine.js is loaded:

     @push('scripts')
         @livewireScripts
         <script src="//unpkg.com/alpinejs" defer></script>
     @endpush
     

3. File Upload Paths

   • Issue: Uploaded files aren’t saved to the expected location.
   • Fix: Configure the upload_disk in config/livewire-form-builder.php:

     'upload_disk' => 'public',
     'upload_path' => 'uploads/forms',
     

4. Livewire Hook Conflicts

   • Issue: Custom Livewire hooks (e.g., mount) interfere with form rendering.
   • Fix: Use protected $listeners or protected $rules in your Livewire component to avoid naming collisions.

Debugging

• Form Not Loading:
  • Check storage/logs/laravel.log for FormRepository errors.
  • Verify the form ID exists in the forms table.
• Validation Errors:
  • Inspect the browser’s console for Livewire validation messages. Use dd($this->submissionData) in the component to debug submitted data.
• Conditional Logic Errors:
  • Temporarily disable rules in the UI to isolate the issue:

    // In a browser console (for testing):
    document.querySelectorAll('[x-data]').forEach(el => {
        el._x = { data: {}, effects: [] };
    });
    

Extension Points

1. Custom Field Types

   • Publish the field views:

     php artisan vendor:publish --tag=livewire-form-builder-views
     

   • Add a new field class (e.g., app/Fields/CustomField.php) and register it in the config:

     'fields' => [
         'custom' => \App\Fields\CustomField::class,
     ],
     

2. Override Default Views

   • Copy resources/views/vendor/livewire-form-builder/ to your project and modify templates (e.g., form-builder.blade.php).

3. Artisan Commands

   • Extend the scaffolding commands:

     php artisan make:livewire-form-builder-command
     

   • Register in app/Console/Kernel.php:

     protected $commands = [
         \Tivents\LivewireFormBuilder\Console\Commands\PublishStubs::class,
         \App\Console\Commands\CustomFormCommand::class,
     ];
     

4. Database Schema

   • Customize the forms and form_fields tables by publishing migrations:

     php artisan vendor:publish --tag=livewire-form-builder-migrations
     

   • Modify database/migrations/xxxx_create_forms_table.php before running migrate.