felixdorn/onboard

Track user onboarding steps.

0.7.0 2022-05-18 15:43 UTC

Requires

• php: ^8.1
• honda/url-pattern-matcher: ^1.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3
• orchestra/testbench: ^6
• pestphp/pest: ^1
• phpstan/phpstan: ^1
• symfony/var-dumper: ^5|^6

MIT

• Félix Dorn

README

Installation

Requires PHP 8.1+ and Laravel 8.x or 9.x

You can install the package via composer:

composer require felixdorn/onboard

Publish the ResumeOnboarding middleware to your app/Http/Middleware directory:

php artisan onboard:middleware

If you're using Inertia, you need to return false when $request->inertia() is true in the skip method of the middleware.

    public function skip(Request $request): bool
    {
        if ($request->inertia()) {
            return false;
        }
        
        return parent::skip($request);
    }

Add it to your app/Http/Kernel.php:

    // ...

    protected $middlewareGroups = [
        'web' => [
            // ...
            \App\Http\Middleware\ResumeOnboarding::class
        ]   
    ]

Then, make sure that your User model uses HasOnboarding.

use Felix\Onboard\Concerns\HasOnboarding;

class User extends Authenticatable {
    use HasOnboarding;
    
    // ...
}

You're all set.

Usage

Add your onboarding steps in app/Providers/AppServiceProvider.php

If you have a lot of steps, you may consider creating an OnboardServiceProvider (don't forget to register it in config/app.php).

use \App\Models\User;
use \Felix\Onboard\Facades\Onboard;

Onboard::add('verify_email')
    ->completedIf(function (User $user) {
        return $user->hasVerifiedEmail(); // or whatever    
    })
    ->skipIf(function () {
        return $user->github_id != null;
    })
    ->route('verification.notice')
    ->allowRoutes(['verification.verify']);

class HomeController extends Controller {
    public function index(\Illuminate\Http\Request $request) {
        return [
            'steps' => $request->user()->onboarding()->toArray()
        ];
    }
}

WARNING: Be careful, closure are memoized (their result are cached) for the duration of a request. This should never be an issue in traditional apps, if you encounter problems, please let us know.

You may call completedIf and skipIf many times, the step will be marked as completed or skipped if all the closures return true.

You may pass a closure to resolve a route lazily:

Onboard::add('create_team')
    ->route(fn () => route('teams.create'));

Globally allowed routes

Regardless of the state of the onboarding process, you may want the user to have access to certain urls, such as a logout page.

Onboard::allow(['/api/*']);

Onboard::allowRoutes(['logout', 'settings.billing']);

Step::allow and Onboard::allow make use of honda/url-pattern-matcher, check it out for more details about how to use pattern matching with Onboard.

Testing

composer test

Onboard for Laravel was created by Félix Dorn under the MIT license.