Breezify Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require codesren/breezify
   php artisan breeze:install breezify
   npm install && npm run dev
   

   This installs Breeze with Fortify as the backend, skipping the default Breeze stack.

2. First Use Case

   • Authentication Flow: Test the default login/registration routes (/login, /register) immediately.
   • Verify Fortify Integration: Check app/Providers/FortifyServiceProvider.php to confirm Fortify’s session handling and authentication logic.
   • Blade Templates: Inspect resources/views/auth/ for pre-built UI components (e.g., login.blade.php, register.blade.php).

Implementation Patterns

Core Workflows

1. Customizing Authentication Logic

   • Override Fortify’s default policies/guards in app/Providers/FortifyServiceProvider.php:

     public function boot()
     {
         Fortify::authenticateUsing(function (Request $request) {
             return CustomAuth::attempt($request->only('email', 'password'));
         });
     }
     

   • Extend Breeze’s Blade components by copying files from resources/views/auth/ to your project and modifying them.

2. Adding Multi-Factor Authentication (MFA)

   • Use Fortify’s built-in MFA support:

     Fortify::enableTwoFactorAuthentication();
     

   • Customize the MFA UI by extending resources/views/auth/two-factor-challenge.blade.php.

3. API Authentication

   • Fortify includes API token support. Generate tokens via:

     use Laravel\Fortify\Actions\CreateNewUser;
     use Laravel\Fortify\Actions\AttemptToAuthenticate;
     

   • Use Sanctum or Passport alongside Fortify for API routes.

4. Session Management

   • Configure session drivers in .env (e.g., SESSION_DRIVER=database).
   • Customize session timeout in app/Providers/FortifyServiceProvider.php:

     Fortify::withSessionConfiguration(function ($session) {
         $session->timeout(1440); // 24 minutes
     });
     

5. Validation Rules

   • Extend Fortify’s validation rules by publishing and modifying:

     php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"
     

   • Override rules in config/fortify.php or create custom rules in app/Rules/.

Integration Tips

• Laravel Mix/Webpack: Use npm run dev or npm run build to compile assets. Customize webpack.mix.js for additional JS/CSS.
• Database Migrations: Fortify adds users, failed_jobs, and sessions tables. Review database/migrations/ for customizations.
• Testing: Use Laravel’s HTTP tests with Fortify’s helpers:

  use Laravel\Fortify\Features;
  Features::testsUsing()->createApplication();
  

• Localization: Override Breeze’s language strings in resources/lang/.

Gotchas and Tips

Pitfalls

1. Fortify vs. Breeze Conflicts

   • Breeze uses Blade views; Fortify handles logic. Avoid mixing Breeze’s AuthController with Fortify’s LoginController.
   • Fix: Stick to Fortify’s controllers (app/Http/Controllers/AuthenticatedSessionController.php) for auth logic.

2. CSRF Token Issues

   • Fortify relies on CSRF protection. Ensure middleware is registered in app/Http/Kernel.php:

     'web' => [
         \App\Http\Middleware\VerifyCsrfToken::class,
     ],
     

3. Session Driver Mismatches

   • If using SESSION_DRIVER=database, ensure the sessions table exists and is properly configured.
   • Debug: Check storage/logs/laravel.log for session-related errors.

4. Email Verification Quirks

   • Fortify’s email verification uses queues. Verify config/fortify.php:

     'features' => [
         Features::registration(),
         Features::emailVerification(),
     ],
     

   • Tip: Test email verification locally with Mail::fake() in tests.

5. Route Caching

   • After customizing routes, clear the route cache:

     php artisan route:clear
     

Debugging Tips

• Fortify Events: Listen to Fortify events for debugging:

  Fortify::authenticated(function (User $user) {
      Log::info('User authenticated', ['user' => $user->id]);
  });
  

• Log Fortify Requests: Add middleware to log auth attempts:

  public function handle($request, Closure $next)
  {
      Log::debug('Auth attempt', ['input' => $request->only('email', 'password')]);
      return $next($request);
  }
  

• Check Fortify’s Published Config: Always publish Fortify’s config before customizing:

  php artisan vendor:publish --tag="fortify-config"
  

Extension Points

1. Custom User Models

   • Extend the default User model by publishing Fortify’s migrations:

     php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider" --tag="migrations"
     

   • Add fields to the users table and update app/Models/User.php.

2. Socialite Integration

   • Fortify supports Socialite. Configure in app/Providers/FortifyServiceProvider.php:

     Fortify::authenticateWithGitHub();
     

   • Customize the redirect URLs in config/services.php.

3. Password Reset Customization

   • Override the password reset view (resources/views/auth/reset-password.blade.php).
   • Extend the reset logic in app/Actions/Fortify/PasswordReset.php.

4. Rate Limiting

   • Fortify includes rate limiting. Adjust in app/Providers/FortifyServiceProvider.php:

     Fortify::limitAttemptsByIp();
     Fortify::limitAttemptsPerMinute(5);
     

5. Testing Fortify

   • Use Fortify’s test helpers to simulate auth flows:

     $response = $this->post('/login', ['email' => 'user@example.com', 'password' => 'password']);
     $response->assertRedirect('/dashboard');