ycore/fortify-ui

A Laravel Fortify-powered authentication UI

v1.3.1 2021-04-08 06:41 UTC

This package is auto-updated.

Last update: 2021-11-08 08:34:29 UTC


README

Introduction

FortifyUI connects the robust authentication features of the Laravel Fortify headless authentication backend with easy-to-install authentication UI.

It provides a simple and comprehensive authentication scaffold. It can also ease the upgrade path for existing projects wishing to move from Laravel UI to the Laravel Fortify authentication provider.

fortify-ui.svg

Requirements

FortifyUI requires Laravel 8.0+. See Upgrading Laravel if necesarry

Latest Version on Packagist

Installation

FortifyUI provides a headless implementation of the Laravel Fortify authentication backend, following the recommendations outlined in the Laravel Fortify documentation.

Authentication views and scaffolding are implemented using FortifyUI-designed or community-contributed frontend packages. FortifyUI doesn't need to be installed seperately. Installing an authentication frontend package, also installs FortifyUI.

Select a FortifyUI authentication frontend to install
fortify-icon.svg Follow the Fortify-tailwind installation instructions to install the tailwindcss-styled authentication UI
fortify-icon.svg Follow the Fortify-unstyled installation instructions to install a completely un-styled authentication UI

You can design your own authentication UI for your frontend library or framework of choice. The fortify-icon.svg Fortify-unstyled package would be an ideal front-end starter to fork.

If you design an authentication front-end for FortifyUI that the community could benefit from, please let us know, and we'd be happy to include reference to it here.

Post-install configuration options

The post-installation configuration options become available once you've installed an authentication frontend package.

The default installation provides sensible configuration defaults. The login, logout, registration and reset-passwords features and routes are enabled by default. If these defaults are sufficient, there is no need for additional configuration.

FortifyUI provides some granular configuration options to customize features, locations and behaviour. The fortify-ui:publish artisan command essentially combines multiple vendor:publish --tag behaviours and conflict-checking to simplify publishing configuration overrides.

ℹ️  Show the post-installation configuration options using:

$ php artisan fortify-ui:publish --help

Enabling features

The following features are enabled in config/fortify.php using the default installation.

    'features' => [
        Features::registration(),
        Features::resetPasswords(),
        //Features::emailVerification(),
        //Features::updateProfileInformation(),
        //Features::twoFactorAuthentication(),
        //Features::twoFactorAuthentication([
            //'confirmPassword' => true,
        //]),
        //Features::updatePasswords(),
    ],

Features can be enabled or disabled editing the config/fortify.php file post-install. See Fortify Features for additional configuration options.

See Two factor authentication on the additional requirements when two factor authentication is enabled.

Two factor authentication

The two factor authentication feature can be enabled in config/fortify.php. The FortifyUIServiceProvider registers the view automatically once the feature is enabled in the config file.

Two factor authentication requires migration of additional fields to the database and additions to the User Model.

Publishing Fortify migrations

$ php artisan fortify:publish --migrations
$ php artisan migrate

Adding the TwoFactorAuthenticatable trait

Add the TwoFactorAuthenticatable trait and hidden fields to app/Models/User.php

use Laravel\Fortify\TwoFactorAuthenticatable;

class User extends Authenticatable
{
    use HasFactory, Notifiable, TwoFactorAuthenticatable;
    ...

    protected $hidden = [
        'two_factor_recovery_codes',
        'two_factor_secret',
    ];
    ...

Publishing the Laravel Fortify configuration

$ php artisan fortify:publish --config

Overwrites the config/fortify.php published during the intial installation with the default configuration provided by Laravel Fortify. See the Laravel Fortify documentation for additional configuration options.

Publishing the FortifyUI configuration

Publishing config/fortify-ui.php allows customising the view locations.

$ php artisan fortify:publish --ui-config

The views section can be used to customize view locations.

'views' => [
    'login' => 'auth.login',
    'register' => 'auth.register',
    'verify-email' => 'auth.verify-email',
    'reset-password' => 'auth.password.reset-password',
    'forgot-password' => 'auth.password.forgot-password',
    'confirm-password' => 'auth.password.confirm-password',
    'two-factor-challenge' => 'auth.password.two-factor-challenge',
    'update-password' => 'profile.update-password',
    'two-factor-authentication' => 'profile.two-factor-authentication',
    'update-profile-information' => 'profile.update-profile-information',
],

Publishing the FortifyUI service provider

Publishing the FortifyUIServiceProvider allows customising many of the actions and view locations for enabled Fortify features.

$ php artisan fortify:publish --provider

Publishes the app/Providers/FortifyUIServiceProvider file and registers it within the providers array of your app configuration file.

...
    public function boot(): void
    {

        Fortify::createUsersUsing(CreateNewUser::class);

        Fortify::loginView(function () {
            return view(config('fortify-ui.views.login'));
        });

        Fortify::confirmPasswordView(function () {
            return view(config('fortify-ui.views.confirm-password'));
        });

        $this->bootFeatures();

    }

...
    protected function bootFeatures(): void
    {
        if (Features::enabled(Features::resetPasswords())) {
            Fortify::resetUserPasswordsUsing(ResetUserPassword::class);

            Fortify::requestPasswordResetLinkView(function () {
                return view(config('fortify-ui.views.forgot-password'));
            });

            Fortify::resetPasswordView(function ($request) {
                return view(config('fortify-ui.views.reset-password'), ['request' => $request]);
            });
        }

        if (Features::enabled(Features::registration())) {
            Fortify::registerView(function () {
                return view(config('fortify-ui.views.register'));
            });
        }

        if (Features::enabled(Features::emailVerification())) {
            Fortify::verifyEmailView(function () {
                return view(config('fortify-ui.views.verify-email'));
            });
        }

        if (Features::enabled(Features::updateProfileInformation())) {
            Fortify::updateUserProfileInformationUsing(UpdateUserProfileInformation::class);
        }

        if (Features::enabled(Features::updatePasswords())) {
            Fortify::updateUserPasswordsUsing(UpdateUserPassword::class);
        }

        if (Features::enabled(Features::twoFactorAuthentication())) {
            Fortify::twoFactorChallengeView(function () {
                return view(config('fortify-ui.views.two-factor-challenge'));
            });
        }
    }
...

The kitchen sink

$ php artisan fortify:publish --all

Publishes all the configuration and provider options for both FortifyUI and Laravel Fortify.

Questions?

Is this a replacement for Laravel Jetstream?

While both FortifyUI and Laravel Jetstream utilizes Laravel Fortify, Jetstream provides both substantial additional functionality and additional scaffolding options, including Laravel Livewire and Intertia, which FortifyUI does not aim to replicate or replace. FortifyUI does however follow the basic recommendations from the Laravel Fortify documentation for implementing an authentication UI scaffold without much of the additional scaffolding.

Can it be used to replace Laravel UI?

Laravel UI has been the de-facto simple Laravel authentication UI scaffold for many development projects, but doesn't include many of the Laravel Fortify features. Laravel UI has been through many iterations and has often been tightly integrated. It would be diffcult to comprehensive predict all upgrade scenarios.

FortifyUI was however created and have been used to migrate some of our internal and client projects from Laravel UI to a Laravel Fortify-based authentication implementation. Many of the granular configuration options exist because we needed them for both new installations and while migrating.

What are the other options?

It is possible to follow the relatively straightforward Laravel Fortify documentation to implement your own authentication UI scaffold - like we did.

Zack Warren published a package with largely similar functionality and a somewhat different design. We may possibly have used that ourselves had we discovered it earlier.

If you are aware of more alternatives, or you create a custom UI scaffolding package that utilizes FortifyUI, please let us know.

Changelog

Please see the Changelog for more information on what has changed recently.

Contributing

Please see Contributing for details.

Security

Should you discover any security-related issues, please email y-core@outlook.com instead of using the issue tracker.

Credits

License

MIT. Please see the License file for more information.