X Form Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require vkm-apps/x-form
   npm install @alpinejs/intersect @alpinejs/collapse
   npm run dev
   

   Verify alpinejs and livewire are installed in your project.

2. Publish Configuration & Assets

   php artisan vendor:publish --provider="VkmApps\XForm\XFormServiceProvider" --tag=xform-config
   php artisan vendor:publish --provider="VkmApps\XForm\XFormServiceProvider" --tag=xform-assets
   

   This generates:

   • config/x-form.php (customize form behavior)
   • Assets in public/vendor/xform (CSS/JS).

3. Basic Blade Component Usage Add the Livewire directive to your Blade layout (e.g., resources/views/layouts/app.blade.php):

   @livewireScripts
   @stack('scripts')
   

   Use a pre-built component in a view (e.g., resources/views/forms/contact.blade.php):

   <x-form.text
       name="email"
       label="Email Address"
       :value="old('email')"
       required
   />
   

4. First Livewire Form Integration Create a Livewire component to handle form submission:

   php artisan make:livewire ContactForm
   

   Update app/Http/Livewire/ContactForm.php:

   public function submit()
   {
       $validated = $this->validate([
           'email' => 'required|email',
       ]);
       // Process data...
   }
   

   Bind the form to the Livewire component in Blade:

   <livewire:contact-form />
   

5. Test the Form Run the development server:

   php artisan serve
   

   Navigate to your form view and submit to verify validation/error handling.

Implementation Patterns

Core Workflows

1. Component-Based Form Building

• Reusable Components: Use <x-form.*> tags for common inputs (e.g., text, email, select, checkbox, editor).

  <x-form.text name="username" label="Username" required />
  <x-form.checkbox name="terms" label="Agree to terms" />
  

• Dynamic Arrays: For nested fields (e.g., multi-step forms, surveys):

  <x-form.dynamic-array name="questions">
      <x-slot name="item">
          <x-form.text name="question" label="Question" />
      </x-slot>
  </x-form.dynamic-array>
  

2. Livewire Integration

• Form Submission: Bind Livewire properties to form fields:

  // Livewire component
  public $email;
  protected $rules = ['email' => 'required|email'];
  
  public function submit()
  {
      $this->validate();
      // Save logic...
  }
  

• Blade Binding:

  <x-form.text name="email" :value="$email" />
  

3. Validation & Errors

• Automatic Error Display: Errors render via AlpineJS/Livewire:

  <x-form.text name="email" :error="$errors->first('email')" />
  

• Custom Validation Rules: Extend via Livewire’s $rules or AlpineJS:

  // AlpineJS (for client-side validation)
  x-data="{ rules: { email: 'required|email' } }"
  

4. Advanced Features

• File Uploads:

  <x-form.file name="avatar" label="Profile Picture" />
  

• Rich Text Editor (YouTube embeds, dynamic content):

  <x-form.editor name="description" />
  

• Conditional Fields: Use AlpineJS x-show or Livewire logic:

  <x-form.text name="phone" x-show="showPhone" />
  

  x-data="{ showPhone: @entangle('show_phone') }"
  

5. Configuration

• Customize global settings in config/x-form.php:

  'default_align' => 'horizontal', // 'horizontal' | 'vertical'
  'editor_options' => [
      'plugins' => ['youtube'],
  ],
  

Integration Tips

With Laravel Validation

• Sync Livewire rules with Laravel’s FormRequest:

  // Livewire component
  use App\Http\Requests\StoreUserRequest;
  
  public function mount(StoreUserRequest $request)
  {
      $this->rules = $request->rules();
  }
  

With Tailwind CSS

• Override default styles in resources/css/app.css:

  .x-form-input {
      @apply border-gray-300 rounded-md;
  }
  .x-form-error {
      @apply text-red-500 text-sm;
  }
  

Dynamic Forms

• Use Livewire’s $emit/$listen for real-time updates:

  // Livewire component
  public function addField()
  {
      $this->fields[] = '';
      $this->emit('fieldAdded');
  }
  

  <div x-data="{ count: 0 }" x-on:fieldAdded="count++">
      <!-- Dynamic fields -->
  </div>
  

Multi-Step Forms

• Leverage Livewire’s $currentStep and AlpineJS for step transitions:

  <template x-for="step in steps" :key="step.id">
      <div x-show="currentStep === @entangle('currentStep').step.id">
          <!-- Step content -->
      </div>
  </template>
  

Testing

• Test Livewire components with Livewire::test():

  public function test_form_submission()
  {
      Livewire::test('contact-form')
          ->set('email', 'test@example.com')
          ->call('submit')
          ->assertSee('Success!');
  }
  

• Use Dusk for end-to-end testing:

  $this->visit('/contact')
       ->fill('email', 'test@example.com')
       ->press('Submit')
       ->assertSee('Success!');
  

Gotchas and Tips

Pitfalls

1. Livewire vs. AlpineJS State Conflicts

   • Issue: AlpineJS may update client-side state before Livewire syncs, causing race conditions.
   • Fix: Use @entangle to bind AlpineJS to Livewire properties:

     <input x-model="@entangle('email')" />
     

   • Debug: Check browser console for Alpine.js: Unable to parse expression errors.

2. File Upload Stuck States

   • Issue: File inputs may not reset after errors or successful submissions.
   • Fix: Manually reset the input in Livewire:

     public function submit()
     {
         $this->validate();
         $this->reset('avatar'); // Reset file input
     }
     

     <x-form.file name="avatar" wire:model="avatar" />
     

3. Editor Initialization Failures

   • Issue: Dynamic editors (e.g., x-form.editor) may fail if AlpineJS loads after Livewire.
   • Fix: Ensure AlpineJS initializes before Livewire:

     @push('scripts')
         @alpinejs
     @endpush
     

4. CSS Class Overrides

   • Issue: Custom Tailwind classes may not apply due to package-specific CSS specificity.
   • Fix: Use !important sparingly or increase specificity:

     .x-form-container .custom-class {
         @apply your-styles !important;
     }
     

5. Dynamic Arrays and Livewire Keys

   • Issue: Livewire may lose track of dynamic array items if keys aren’t preserved.
   • Fix: Use wire:key on dynamic items:

     <div wire:key="field-{{ $index }}">
         <x-form.text name="fields.{{ $index }}" />
     </div>
     

6. AlpineJS Namespace Collisions

   • Issue: Duplicate x-data or x-model bindings if AlpineJS is loaded multiple times.
   • Fix: Isolate AlpineJS scopes:

     <div x-data="{ /* isolated scope */ }">
         <!-- Form components -->
     </div>
     

Debugging Tips

1. Livewire Logs Enable Livewire’s debug mode in .env:

   LIVEWIRE_LOG_LEVEL=debug
   

   Check logs for hydration errors or property updates.

2. AlpineJS DevTools Use the Alpine.js DevTools browser extension to inspect reactive state.

3. Blade Debugging Dump variables to