Filament Breezy Documentation

Two-Factor Authentication (2FA) sessions in Breezy are governed by the following rules:

• Guard Scope: By default, Breezy uses the same guard defined on your Filament Panel (defaulting to 'web'). Only panels that have registered the BreezyCore plugin have access to 2FA.
• Multi-Panel Behavior: If multiple panels use 2FA and share the same guard, a user only needs to enter their OTP once for the duration of the session.
• Session Lifetime: The 2FA session lasts for the duration of the Laravel session lifetime. Users must re-enter the OTP if they log out or if the session expires.
• Interaction with Email Verification: When 2FA is configured, the user is prompted for the OTP code before being prompted for email verification (MustVerifyEmail).

To enable Breezy features, add the BreezyCore plugin to your Filament Panel configuration using the plugin() or plugins([]) method.

use Jeffgreco13ilament-breezy\
BreezyCore;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            BreezyCore::make()
        ]);
}

You can add new custom Livewire components to the My Profile page by extending Jeffgreco13\FilamentBreezy\Livewire\MyProfileComponent and registering them with myProfileComponents().

// 1. Create component extending MyProfileComponent
class MyCustomComponent extends MyProfileComponent
{
    // ... implement form() and submit()
}

// 2. Register with Breezy
BreezyCore::make()
    ->myProfileComponents([MyCustomComponent::class])

// 3. Or override an existing component
BreezyCore::make()
    ->myProfileComponents([
        'update_password' => MyCustomComponent::class,
    ])

To install Filament Breezy, first require the package via Composer and then run the provided artisan installation command to set up the necessary components.

composer require jeffgreco13/filament-breezy
php artisan breezy:install

To run the test suite for this project, use the following composer command.

composer test

1. Add the Jeffgreco13\FilamentBreezy\Traits\TwoFactorAuthenticatable trait to your User model.
2. Enable it in the Breezy configuration using enableTwoFactorAuthentication().

// In User model
class User extends Authenticatable
{
    use TwoFactorAuthenticatable;
}

// In Breezy configuration
BreezyCore::make()
    ->enableTwoFactorAuthentication(
        force: false, // force user to enable 2FA
        action: CustomTwoFactorPage::class, // optional custom page
        authMiddleware: MustTwoFactor::class, // optional custom middleware
        scopeToPanel: true, // scope 2FA to current panel
    )

Because Filament Breezy uses additional Tailwind classes, you should add its view paths to your custom Filament theme's CSS file (typically located at resources/css/filament/admin/theme.css) to ensure styles are compiled correctly.

Add the following @source directive to your CSS file:

@source '../../../../vendor/jeffgreco13/filament-breezy/resources/**/*';

Breezy uses the authGuard defined on your Filament Panel. You can customize this in your PanelProvider. Ensure that the model used by your chosen guard extends Laravel's Authenticatable class.

use Jeffgreco13ilament-breezy\BreezyCore;

class CustomersPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ...
            ->authGuard('customers')
            ->plugin(
                BreezyCore::make()
            );
    }
}

To use avatars, your User model must implement Filament\Models\Contracts\HasAvatar and provide a getFilamentAvatarUrl() method. You must also add an avatar_url column to your users table.

To customize the upload component, use avatarUploadComponent().

// In your User model
class User extends Authenticatable implements FilamentUser, HasAvatar
{
    public function getFilamentAvatarUrl(): ?string
    {
        return $this->avatar_url ? Storage::url($this->avatar_url) : null;
    }
}

// In your Breezy configuration
BreezyCore::make()
    ->avatarUploadComponent(fn() => FileUpload::make('avatar_url')->disk('profile-photos'))

If you need to customize the plugin's UI, you can publish its Blade views to your application using the following artisan command:

php artisan vendor:publish --tag="filament-breezy-views"

For the TwoFactorAuthentication Livewire component and other Breezy 2FA features to work, your User model must implement the Jeffgreco13\FilamentBreezy\Traits\TwoFactorAuthenticatable trait. This trait provides the necessary methods used by the component, such as:

• enableTwoFactorAuthentication()
• disableTwoFactorAuthentication()
• confirmTwoFactorAuthentication()
• setTwoFactorSession()
• reGenerateRecoveryCodes()
• getTwoFactorQrCodeUrl()