Laravel 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 (e.g., AppServiceProvider@boot):

   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:

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

Implementation Patterns

Core Workflows

1. Step Definition:

   • Use Onboard::addStep() to define steps with:
     • title(): Human-readable name.
     • link(): URL to navigate when clicked.
     • cta(): Call-to-action text (e.g., "Start").
     • completeIf(): Closure to check completion (e.g., fn ($user) => $user->posts->count() > 0).
   • Example:

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

2. Dynamic Completion Logic:

   • Use closures for flexible completion checks:

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

3. Rendering Steps:

   • Progress Bar:

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

   • Modal/Tooltip: Trigger onboarding steps via JavaScript:

     document.querySelector('.onboard-step').addEventListener('click', (e) => {
         window.location.href = e.target.dataset.link;
     });
     

4. Conditional Steps:

   • Skip steps based on user attributes:

     Onboard::addStep('Set Preferences')
         ->visibleIf(fn ($user) => $user->preferences->isEmpty())
         ->completeIf(fn ($user) => !$user->preferences->isEmpty());
     

5. Integration with Auth Events:

   • Reset onboarding on user updates:

     use Spatie\Onboard\Events\UserOnboardingReset;
     
     User::updated(function ($user) {
         event(new UserOnboardingReset($user));
     });
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

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

     php artisan migrate:fresh --seed
     

     if testing locally.

2. Closure Scope:

   • Closures in completeIf()/visibleIf() lose scope. Use use ($user) or arrow functions:

     ->completeIf(fn () => auth()->user()->hasVerifiedEmail());
     

3. Caching Issues:

   • Steps are cached after registration. Clear cache if steps aren’t updating:

     php artisan onboard:clear-cache
     

4. Step Order:

   • Steps are registered in the order they’re added. Reorder dynamically if needed:

     Onboard::reorderSteps([3, 1, 2]); // Reorders steps by their IDs
     

5. Testing:

   • Mock the Onboard facade in tests:

     $this->partialMock(Onboard::class, function ($mock) {
         $mock->shouldReceive('steps')->andReturn([...]);
     });
     

Debugging Tips

• Log Step Completion: Add a temporary check to debug why a step isn’t completing:

  ->completeIf(fn ($user) => {
      \Log::info('Checking completion for', ['user_id' => $user->id, 'step' => 'Complete Profile']);
      return $user->profile->isComplete();
  });
  

• Inspect User Onboarding: Dump the user’s onboarding state in Tinker:

  php artisan tinker
  >>> $user = App\User::first();
  >>> $user->onboarding()->steps
  

Extension Points

1. Custom Step Models: Extend the Spatie\Onboard\Models\OnboardStep model to add custom fields:

   php artisan make:model OnboardStepExtension --extends=Spatie\Onboard\Models\OnboardStep
   

2. Event Listeners: Listen for onboarding events (e.g., StepCompleted):

   Onboard::stepCompleted(function ($user, $step) {
       // Send notification or log completion
   });
   

3. API Endpoints: Expose onboarding progress via API:

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

4. Localization: Localize step titles/CTAs by publishing the language files:

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