Breeze Laravel Package

Getting Started

Run the installer to scaffold authentication:

composer require laravel/breeze --dev
php artisan breeze:install

Choose your preferred stack (Blade, Inertia/Vue, Livewire, or API). For Blade, run:

php artisan breeze:install blade

Then install dependencies:

npm install && npm run dev

First use case: Test the auth flow by visiting /login, registering a user, and verifying email functionality.

Implementation Patterns

Core Workflow

1. Authentication Routes & Controllers

   • Routes are defined in routes/auth.php (Blade) or routes/web.php (Inertia/Livewire).
   • Controllers (app/Http/Controllers/Auth/...) handle registration, login, password reset, and email verification.
   • Pattern: Extend AuthController or RegisteredUserController for custom logic (e.g., add fields to registration).

2. Views & Components

   • Blade: Views in resources/views/auth/ (e.g., login.blade.php).
   • Inertia/Vue: Components in resources/js/Pages/Auth/ (e.g., Login.tsx).
   • Livewire: Components in app/Http/Livewire/Auth/ (e.g., Login.php).
   • Pattern: Override default views by copying them to your project and modifying. Use @extends or layout props.

3. Middleware

   • Auth middleware (auth, guest) is auto-registered in app/Http/Kernel.php.
   • Pattern: Add custom middleware to the auth group:

     'auth' => [
         \App\Http\Middleware\VerifyCustomRole::class,
     ],
     

4. Session & State

   • Blade/Livewire: Uses Laravel’s default session.
   • Inertia: Uses Inertia’s SSR/CSR session handling. Ensure app/Http/Middleware/HandleInertiaRequests.php is configured.
   • API: Uses Sanctum for token-based auth. Configure CORS in config/cors.php.

5. Testing

   • Pest tests are included in tests/Feature/Auth/.
   • Pattern: Extend AuthenticationTestCase for custom assertions:

     use Tests\TestCase;
     use Laravel\Breeze\AuthenticationTestCase;
     
     class CustomAuthTest extends AuthenticationTestCase {
         // Override methods like `login()` or `register()`
     }
     

Integration Tips

• Custom User Model/Fields: Modify app/Models/User.php and update the migration. Re-run:

  php artisan migrate:fresh
  

  Update validation in app/Http/Requests/Auth/RegisterRequest.php.

• Socialite Providers: Install laravel/socialite and configure in config/services.php. Extend SocialAuthController:

  use Laravel\Socialite\Facades\Socialite;
  
  public function redirectToProvider($provider) {
      return Socialite::driver($provider)->redirect();
  }
  

• Multi-Factor Auth (MFA): Use laravel/breeze-two-factor or integrate laravel/fortify for advanced MFA.

• API Stack: Sanctum tokens are stored in the personal_access_tokens table. Use:

  use Laravel\Sanctum\PersonalAccessToken;
  
  $token = PersonalAccessToken::createToken('token-name');
  

Gotchas and Tips

Pitfalls

1. CSRF Token Mismatch (Blade/Inertia)

   • Issue: Form submissions fail with CSRF token mismatch.
   • Fix: Ensure @csrf is in Blade forms or Ziggy is configured for Inertia:

     // resources/js/app.js
     import { createInertiaApp } from '@inertiajs/react';
     createInertiaApp({
         resolve: (name) => require(`./Pages/${name}.tsx`),
         setup({ el, App, props }) {
             return createRoot(el).render(<App {...props} />);
         },
     });
     

2. Livewire Validation Errors

   • Issue: Validation messages don’t appear.
   • Fix: Ensure wire:model and wire:ignore are correctly set in Livewire components. Check app/Http/Livewire/Auth/Login.php for validation rules.

3. Inertia SSR Hydration Mismatches

   • Issue: React errors like Hydration failed during SSR.
   • Fix: Use dangerouslySetInnerHTML for dynamic content or disable SSR for specific pages:

     // resources/js/Pages/Auth/Login.tsx
     const { children, ...props } = usePageProps<PageProps>();
     return <AuthLayout {...props}>{children}</AuthLayout>;
     

4. Email Verification Stuck in Queue

   • Issue: Verification emails aren’t sent.
   • Fix: Check config/mail.php and queue worker:

     php artisan queue:work
     

   • Ensure Mailable classes (e.g., VerifyEmail.php) are in app/Mail.

5. Tailwind Dark Mode Conflicts

   • Issue: Dark mode doesn’t persist.
   • Fix: Ensure tailwind.config.js includes:

     darkMode: 'class',
     

   • Check for conflicting CSS in resources/css/app.css.

Debugging Tips

• Log Auth Events: Use Laravel’s auth listeners in app/Providers/AuthServiceProvider.php:

  public function boot() {
      Auth::authenticated(function ($user) {
          Log::info("User logged in: {$user->email}");
      });
  }
  

• Dump Request Data: Add to app/Http/Middleware/HandleInertiaRequests.php (Inertia):

  public function share(Request $request): array {
      return array_merge(parent::share($request), [
          'debug' => $request->user()?->toArray(),
      ]);
  }
  

• Test API Tokens: Use Tinker to inspect Sanctum tokens:

  php artisan tinker
  >>> \App\Models\User::first()->createToken('test-token')->plainTextToken
  

Extension Points

1. Custom Auth Logic:

   • Override controllers (e.g., app/Http/Controllers/Auth/RegisteredUserController.php).
   • Example: Add a custom field to registration:

     // app/Http/Requests/Auth/RegisterRequest.php
     public function rules() {
         return [
             'name' => 'required|string|max:255',
             'email' => 'required|email|unique:users',
             'password' => 'required|confirmed|min:8',
             'premium' => 'sometimes|boolean', // Custom field
         ];
     }
     

2. Modify Views:

   • Copy resources/views/auth/login.blade.php to your project and customize.
   • For Inertia, extend Login.tsx:

     // resources/js/Pages/Auth/Login.tsx
     export default function Login({ status, canResetPassword }: LoginProps) {
         return (
             <GuestLayout>
                 <div className="max-w-md py-8">
                     <AuthCard>
                         <Head title="Log in" />
                         <Logo />
                         <ValidationErrors className="mb-4" />
                         <form method="POST" action={route('login')}>
                             <TextInput
                                 name="email"
                                 type="email"
                                 required
                                 label="Email"
                                 value={old('email', '')}
                             />
                             {/* Add custom fields */}
                             <TextInput
                                 name="premium"
                                 type="checkbox"
                                 label="Premium User"
                             />
                             <PrimaryButton className="mt-4">
                                 Log in
                             </PrimaryButton>
                         </form>
                     </AuthCard>
                 </div>
             </GuestLayout>
         );
     }
     

3. Hook into Auth Events:

   • Listen for events in AuthServiceProvider:

     public function boot() {
         Auth::attempting(function ($user, $password) {
             Log::debug("Login attempt for: {$user->email}");
         });
     }
     

4. Custom Password Reset:

   • Extend ForgotPasswordController and override sendResetLinkEmail:

     public function sendResetLinkEmail(Request $request) {
         $this->validate($request, ['email' => ['required', 'email']]);
     
         // Custom logic (e.g., send SMS instead of email)
         SMS::to($request->email)->send('Reset password code: ' . Str::random(6));
     
         return back()->with('status', __("Password reset link sent!"));
     }
     

5. API Rate Limiting:

   • Configure Sanctum’s throttle in app/Providers/AuthServiceProvider.php:

     Sanctum::throttlePersonalAccessTokensPerMinute(5);
     Sanctum::throttlePersonalAccessTokensPerHour(100);