Getting Started

Minimal Setup

Installation

composer require jeffgreco13/filament-breezy

Publish the package assets and config:

php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-config"
php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-assets"

Service Provider Registration Add the service provider to config/app.php under providers:
```
JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider::class,
```

First Use Case Register the FilamentBreezyPlugin in your Filament panel provider:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentBreezyPlugin::make());
}

Run Migrations
```
php artisan migrate
```

Where to Look First

Configuration: config/filament-breezy.php (customize validation, branding, and features like 2FA enforcement).
Plugin Registration: app/Providers/Filament/AdminPanelProvider.php (ensure the plugin is added).
User Model: Extend JeffGreco13\FilamentBreezy\Models\User or configure the package to use your existing model via the config.

Implementation Patterns

Core Workflows

1. Profile Management

Avatar Uploads: Use the built-in avatar upload field in the MyProfile page. Customize the disk and path in the config:
```
'avatar' => [
    'disk' => 'public',
    'path' => 'avatars',
],
```
Custom Fields: Extend the profile form by publishing and modifying the view:
```
php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-views"
```
Then add fields to resources/views/vendor/filament-breezy/profile/form.blade.php.

2. Password and Security

Password Updates: The package includes a pre-built UpdatePassword page with customizable validation. Override rules in the config:

'password' => [
    'min_length' => 12,
    'require_uppercase' => true,
    'require_lowercase' => true,
    'require_numbers' => true,
    'require_symbols' => true,
],

Password-Confirmed Actions: Protect sensitive actions (e.g., deleting a record) with the ConfirmPasswordAction:

use JeffGreco13\FilamentBreezy\Actions\ConfirmPasswordAction;

public static function table(Table $table): Table
{
    return $table
        ->actions([
            ConfirmPasswordAction::make('delete')
                ->action(function (Table $table) {
                    // Your delete logic
                }),
        ]);
}

3. Two-Factor Authentication (2FA)

Enforce 2FA: Enable in the config:

'two_factor' => [
    'enforce' => true,
],

Recovery Codes: Generate and manage recovery codes via the TwoFactorAuth page. Customize the number of codes in the config:
```
'two_factor' => [
    'recovery_codes' => [
        'count' => 10,
    ],
],
```
Passkey Authentication: Enable via the config:
```
'passkey' => [
    'enabled' => true,
],
```

4. Sanctum Tokens

Token Management: The SanctumTokens page allows users to create, revoke, and list personal access tokens. Customize token permissions in the config:
```
'sanctum' => [
    'abilities' => [
        'create',
        'read',
        'update',
        'delete',
    ],
],
```

5. Login Flow

Custom Login: Extend the default login logic by publishing the login view and modifying it:

php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-views"

Socialite Integration: Add social login providers (e.g., Google, GitHub) by extending the Login controller or using Filament’s built-in socialite support.

Integration Tips

Custom User Model: If you’re not using Laravel’s default User model, configure the package to use your model in config/filament-breezy.php:
```
'models' => [
    'user' => App\Models\User::class,
],
```
Ensure your model uses the MustVerifyEmail, MustVerifyTwoFactor, and HasApiTokens traits if applicable.
Localization: Translate the package’s strings by publishing the language files:
```
php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-lang"
```
Then add translations to resources/lang/{locale}/filament-breezy.php.
Theming: Customize the package’s CSS by publishing the assets and overriding the styles:
```
php artisan vendor:publish --provider="JeffGreco13\FilamentBreezy\FilamentBreezyServiceProvider" --tag="filament-breezy-assets"
```
Add your CSS to public/vendor/filament-breezy/css/filament-breezy.css.
API Integration: Use Sanctum tokens for API authentication. The SanctumTokens page generates tokens that can be used in API requests:
```
Authorization: Bearer {sanctum_token}
```
Teams Support: If you’re using Laravel’s HasTeams trait, ensure your user model includes it and configure the package to support teams in the config:
```
'teams' => [
    'enabled' => true,
],
```

Gotchas and Tips

Pitfalls

Migration Conflicts:
- If you’ve customized Laravel’s default users table, the package’s migrations might conflict. Review the migrations in database/migrations/ and adjust them to match your schema before running php artisan migrate.
2FA Enforcement:
- Enforcing 2FA ('enforce' => true) will block all users who haven’t enabled it. Test this in a staging environment first, as it can lock out users unexpectedly.
Passkey Browser Support:
- Passkey authentication requires modern browsers (Chrome, Edge, Safari). Test thoroughly across browsers, especially if targeting older users.
Sanctum Token Permissions:
- Sanctum tokens inherit the user’s permissions. If you customize token abilities, ensure they align with your application’s security requirements.
Avatar Storage:
- Avatars are stored using Laravel’s filesystem. Ensure the configured disk ('disk' => 'public') exists and is writable:
```
php artisan storage:link
```

Debugging

Login Issues:
- Clear the session and cache if users are unable to log in:
```
php artisan cache:clear
php artisan session:clear
```
- Check the sessions and failed_jobs tables for errors.
2FA Errors:
- If 2FA fails silently, enable debug mode in the config:
```
'two_factor' => [
    'debug' => true,
],
```
- Check the logs for JeffGreco13\FilamentBreezy entries.
CSRF Token Mismatch:
- If you encounter CSRF token errors on the profile or password pages, ensure your Filament panel’s middleware includes web:
```
->middleware([
    'web',
    'auth',
]),
```
Passkey Debugging:
- Passkey errors often relate to browser compatibility or WebAuthn API issues. Test in incognito mode and check the browser’s console for errors.

Tips

Custom Validation: Extend the package’s validation rules by creating a custom form or using Filament’s form modifiers. For example, to add a custom rule to the password update form:

use JeffGreco13\FilamentBreezy\Forms\Components\PasswordField;

PasswordField::make('password')
    ->rules([
        'required',
        'confirmed',
        'custom_rule|arg1,arg2',
    ]),

Conditional Features: Disable features based on user roles or environments. For example, disable 2FA in development:

Filament Breezy Laravel Package