Laravel Livewire Onboard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-onboard
   

   Publish the migration:

   php artisan vendor:publish --provider="Spatie\Onboard\OnboardServiceProvider" --tag="migrations"
   

   Run migrations:

   php artisan migrate
   

2. Define Onboarding Steps: Configure steps in a service provider's boot() method (e.g., AppServiceProvider):

   use Spatie\Onboard\Facades\Onboard;
   
   Onboard::addStep('Complete Profile')
       ->link('/profile')
       ->cta('Complete')
       ->completeIf(fn ($user) => $user->profile->isComplete());
   

3. First Use Case: Display the onboarding progress in a Blade template:

   @auth
       @if(auth()->user()->onboarding()->inProgress())
           <div class="onboarding-progress">
               @foreach(auth()->user()->onboarding()->steps as $step)
                   <div class="{{ $step->complete() ? 'complete' : 'pending' }}">
                       {{ $step->title }}
                   </div>
               @endforeach
           </div>
       @endif
   @endauth
   

Implementation Patterns

Core Workflows

1. Step Definition:

   • Use Onboard::addStep() in a centralized location (e.g., AppServiceProvider).
   • Chain methods for clarity:

     Onboard::addStep('Verify Email')
         ->link('/email/verify')
         ->cta('Verify Now')
         ->completeIf(fn ($user) => $user->hasVerifiedEmail());
     

2. Dynamic Step Logic:

   • Leverage closures for flexible completion checks:

     ->completeIf(fn ($user) => $user->roles()->where('name', 'admin')->exists())
     

3. Livewire Integration:

   • Use Livewire to dynamically update onboarding state:

     public function completeStep($stepId) {
         $user = auth()->user();
         $user->onboarding()->completeStep($stepId);
         $this->emit('onboardingUpdated');
     }
     

   • Render progress in Livewire components:

     <div wire:ignore>
         @foreach($user->onboarding()->steps as $step)
             <button wire:click="completeStep({{ $step->id }})">
                 {{ $step->cta }}
             </button>
         @endforeach
     </div>
     

4. Middleware for Onboarding Gating:

   • Protect routes until onboarding is complete:

     Route::middleware(['auth', 'onboarding'])->group(function () {
         Route::get('/dashboard', [DashboardController::class, 'index']);
     });
     

   • Create middleware:

     public function handle(Request $request, Closure $next) {
         if (auth()->user()->onboarding()->inProgress()) {
             return redirect()->route('onboarding.index');
         }
         return $next($request);
     }
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • Ensure the onboard_steps table migration doesn’t conflict with existing tables. Run:

     php artisan migrate --pretend
     

     to verify before applying.

2. Closure Scope:

   • Avoid referencing undefined variables in completeIf closures. Use explicit dependencies:

     ->completeIf(fn ($user) => $user->profile->isComplete())
     

     instead of relying on global state.

3. Livewire State Sync:

   • If using Livewire, manually refresh the component after completing steps:

     $this->dispatch('refreshOnboarding');
     

     and listen in the component:

     protected $listeners = ['refreshOnboarding' => '$refresh'];
     

4. Caching Quirks:

   • Clear cached configurations if steps aren’t updating:

     php artisan config:clear
     

Debugging Tips

1. Inspect Steps:

   • Dump steps for debugging:

     dd(auth()->user()->onboarding()->steps->toArray());
     

2. Check Completion Logic:

   • Test completeIf conditions in isolation:

     $user = auth()->user();
     dd($user->profile->isComplete()); // Verify logic
     

3. Middleware Debugging:

   • Temporarily disable middleware to isolate issues:

     Route::middleware(['auth'])->group(function () { ... });
     

Extension Points

1. Custom Step Models:

   • Extend the Spatie\Onboard\Models\Step model for additional fields:

     php artisan make:model OnboardingStep --extends="Spatie\Onboard\Models\Step"
     

2. Event Listeners:

   • Trigger actions when steps are completed:

     Onboard::completed(function ($user, $step) {
         // Send notification, log analytics, etc.
     });
     

3. API Integration:

   • Expose onboarding status via API:

     Route::get('/api/onboarding', function () {
         return auth()->user()->onboarding()->steps;
     });