Formcraft Laravel Package

Getting Started

First Steps

1. Installation

   composer require skywalker-labs/formcraft
   php artisan vendor:publish --provider="SkywalkerLabs\Formcraft\FormcraftServiceProvider" --tag="config"
   php artisan migrate
   

   • Verify the package is registered in config/app.php under providers.

2. Basic Setup

   • Publish the default config:

     php artisan vendor:publish --provider="SkywalkerLabs\Formcraft\FormcraftServiceProvider" --tag="config"
     

   • Update config/formcraft.php to match your app’s needs (e.g., theme, storage paths).

3. First Use Case: Simple Form

   • Create a form definition in a Blade view or Livewire component:

     use SkywalkerLabs\Formcraft\Facades\Formcraft;
     
     $form = Formcraft::make('contact-form')
         ->addText('name', 'Name')
         ->addEmail('email', 'Email')
         ->addSubmit('submit', 'Send');
     

   • Render it in a Blade template:

     {!! $form->render() !!}
     

4. Livewire Integration

   • Extend FormcraftLivewire to handle form submissions:

     use SkywalkerLabs\Formcraft\Livewire\FormcraftLivewire;
     
     class ContactForm extends FormcraftLivewire
     {
         public $form = 'contact-form';
     }
     

   • Use in Blade:

     <livewire:contact-form />
     

Implementation Patterns

1. Form Definition Workflows

• Dynamic Forms: Build forms programmatically in controllers or Livewire components:

  $form = Formcraft::make('dynamic-form')
      ->addSelect('country', 'Country', ['US' => 'USA', 'CA' => 'Canada'])
      ->addCheckbox('terms', 'Accept Terms');
  

• Reusable Forms: Store form definitions in a database or config file for sharing across views.

2. Theme & Styling

• Bootstrap/Tailwind Support:
  • Set the theme in config/formcraft.php:

    'theme' => 'tailwind', // or 'bootstrap'
    

  • Customize via CSS or Tailwind classes (e.g., class="formcraft-input w-64").

3. Validation & Submission

• Built-in Validation:

  $form = Formcraft::make('signup-form')
      ->addText('username', 'Username')
      ->rules('username', 'required|min:3');
  

• Livewire Submission Handling:

  protected function submit()
  {
      $data = $this->validate();
      // Process $data (e.g., save to DB)
  }
  

4. Component Customization

• Extend Components: Override default components (e.g., TextInput) by publishing views:

  php artisan vendor:publish --provider="SkywalkerLabs\Formcraft\FormcraftServiceProvider" --tag="views"
  

• Add Custom Components: Implement FormcraftComponent interface:

  class CustomComponent implements FormcraftComponent {
      public function render(): string { ... }
  }
  

5. Accessibility (a11y)

• Automatic Labels & ARIA: Ensure forms are accessible by default.
• Custom Attributes:

  $form->addText('name', 'Name')->attr('aria-describedby', 'name-help');
  

Gotchas and Tips

Pitfalls

1. Livewire Caching Issues:
   • Clear Livewire cache if forms render incorrectly:

     php artisan livewire:discover
     

2. Theme Conflicts:
   • Tailwind/Bootstrap classes may clash with your app’s CSS. Use !important sparingly or scope Formcraft styles:

     .formcraft { @apply ... }
     

3. Validation Overrides:
   • Rules defined in the form override global validation. Use ->rules()->merge() for additive rules.

Debugging Tips

• Log Form Data:

  $form->onSubmit(function ($data) {
      \Log::info('Submitted:', $data);
  });
  

• Inspect Rendered HTML:
  • Temporarily disable minification in config/formcraft.php:

    'minify' => false,
    

Extension Points

1. Custom Storage:
   • Override form storage (e.g., database) by binding a custom FormcraftStorage:

     $app->bind('formcraft.storage', function () {
         return new CustomFormStorage();
     });
     

2. Event Hooks:
   • Listen for form events (e.g., formcraft.before_submit):

     Formcraft::listen('formcraft.before_submit', function ($form, $data) {
         // Modify $data or cancel submission
     });
     

3. Localization:
   • Publish language files and extend translations:

     php artisan vendor:publish --provider="SkywalkerLabs\Formcraft\FormcraftServiceProvider" --tag="lang"
     

Pro Tips

• Form Templates: Use Blade includes for multi-step forms:

  @include('forms.partials.step1', ['form' => $form->step('step1')])
  

• Conditional Fields:

  $form->addText('address')->conditional('show_address', true);
  

• Performance: Disable unused components (e.g., ->disableCsrf() for APIs) and enable minify in production.