Laravel Livewire Steps Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require satoved/laravel-livewire-steps
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Satoved\LivewireSteps\LivewireStepsServiceProvider"
   

2. First Use Case: Create a Livewire component for your wizard:

   php artisan make:livewire WizardComponent
   

   Define steps as form objects in the component:

   use Satoved\LivewireSteps\LivewireSteps;
   use Livewire\Attributes\Rule;
   
   public function mount()
   {
       $this->steps = [
           new StepOneForm(),
           new StepTwoForm(),
           // Add more steps as needed
       ];
   }
   
   public function render()
   {
       return LivewireSteps::make($this->steps);
   }
   

3. Register the Component: Add the component to your Blade view:

   @livewire('wizard-component')
   

Implementation Patterns

Step Definition

1. Form Objects as Steps: Each step is a Livewire form object (class extending Livewire\Component). Example:

   class StepOneForm extends Livewire\Component
   {
       public $name;
   
       public function rules()
       {
           return ['name' => 'required|min:3'];
       }
   
       public function render()
       {
           return view('steps.step-one');
       }
   }
   

2. Step Navigation: Use nextStep() and prevStep() methods provided by the package:

   public function nextStep()
   {
       $this->validate();
       $this->steps->next();
   }
   
   public function prevStep()
   {
       $this->steps->prev();
   }
   

Workflows

1. Multi-Step Forms:

   • Define each step as a separate form object.
   • Use LivewireSteps::make() to render the wizard UI.
   • Handle validation and submission per step.

2. Dynamic Steps: Load steps dynamically based on user input:

   public function mount()
   {
       $this->steps = collect();
       if ($this->shouldShowStepOne()) {
           $this->steps->push(new StepOneForm());
       }
       if ($this->shouldShowStepTwo()) {
           $this->steps->push(new StepTwoForm());
       }
   }
   

3. Custom UI: Override the default template by publishing views:

   php artisan vendor:publish --tag=livewire-steps-views
   

   Then customize resources/views/vendor/livewire-steps/steps.blade.php.

Integration Tips

1. Validation: Validate each step before proceeding:

   protected $rules = [
       'step_one.name' => 'required',
       'step_two.email' => 'required|email',
   ];
   

2. Progress Tracking: Use the currentStep property to track progress:

   public function render()
   {
       return view('livewire.wizard', [
           'currentStep' => $this->steps->current(),
           'totalSteps' => $this->steps->count(),
       ]);
   }
   

3. Final Submission: Handle form submission after all steps are completed:

   public function submit()
   {
       $this->validate();
       // Save data or perform final action
       session()->flash('success', 'Form submitted successfully!');
   }
   

Gotchas and Tips

Pitfalls

1. Step Indexing: Ensure steps are indexed correctly in the steps array/collection. Out-of-order steps may cause navigation issues.

2. Form State Persistence: Livewire form objects retain state between steps. Clear data if needed:

   public function resetForm()
   {
       $this->reset();
       $this->steps->each(fn ($step) => $step->reset());
   }
   

3. Validation Errors: Validate each step before proceeding to avoid silent failures. Use:

   public function nextStep()
   {
       $this->validate();
       $this->steps->next();
   }
   

Debugging

1. Step Navigation Issues: Check if nextStep()/prevStep() methods are correctly bound to buttons in the Blade view.

2. Form Data Loss: Ensure all form objects are properly instantiated and retained in the steps property.

3. UI Rendering: If the wizard doesn’t render, verify:

   • The LivewireSteps::make() method is called in the render() method.
   • All step classes extend Livewire\Component.

Config Quirks

1. Default Configuration: The package uses minimal configuration. Customize via config/livewire-steps.php if needed:

   'default_step' => 0, // Start from step 0
   'allow_back' => true, // Allow going back to previous steps
   

2. Step Classes: Ensure step classes are autoloaded. If using namespaces, register them in composer.json:

   "autoload": {
       "psr-4": {
           "App\\Steps\\": "app/Steps/"
       }
   }
   

Extension Points

1. Custom Templates: Override the default Blade templates for steps, progress bars, or navigation buttons.

2. Step Events: Listen for step changes via Livewire hooks:

   protected $listeners = ['stepChanged' => 'handleStepChange'];
   
   public function handleStepChange($step)
   {
       // Custom logic when step changes
   }
   

3. Dynamic Step Loading: Load steps asynchronously if they are resource-intensive:

   public function loadStep($stepClass)
   {
       $this->steps->push(new $stepClass());
   }