Breeze Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require laravel/breeze --dev
   php artisan breeze:install blade  # or vue/react/livewire
   npm install && npm run dev
   php artisan migrate
   

   • Choose your preferred stack (blade, vue, react, or livewire) during installation.

2. First Use Case:

   • Access /login to test authentication flow.
   • Register a new user via /register.
   • Verify email functionality (if enabled in AuthServiceProvider).

3. Key Files to Explore:

   • app/Http/Controllers/Auth/ (Login, Registration, Password controllers).
   • resources/views/auth/ (Blade templates) or resources/js/Pages/Auth/ (Inertia/Vue/React).
   • routes/web.php (Authentication routes).
   • app/Providers/AuthServiceProvider.php (Guard configuration).

Implementation Patterns

Core Workflows

1. Authentication Flow

• Login/Register:
  • Use LoginController/RegisteredUserController as base classes.
  • Extend validation rules in LoginRequest/RegisterRequest:

    public function rules()
    {
        return [
            'email' => ['required', 'string', 'email', 'max:255'],
            'password' => ['required', 'string', 'min:8'],
            // Custom rules
            'terms' => ['accepted', 'required'],
        ];
    }
    

• Password Reset:
  • Extend ForgotPasswordController/NewPasswordController for custom logic (e.g., add CAPTCHA):

    protected function validator(array $data)
    {
        return Validator::make($data, [
            'email' => ['required', 'email'],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
            'captcha' => ['required', 'string', 'captcha'], // Custom rule
        ]);
    }
    

2. Session Handling

• Custom Guards: Modify AuthServiceProvider to add guards (e.g., API token auth):

  protected function guard()
  {
      return auth()->guard($this->apiGuard) ?: parent::guard();
  }
  

• Middleware: Use auth middleware in routes:

  Route::middleware(['auth:sanctum'])->group(function () {
      // API routes
  });
  

3. Frontend Integration

• Blade: Extend app/views/layouts/app.blade.php for shared layouts. Use @auth directive for conditional rendering:

  @auth
      <a href="{{ route('dashboard') }}">Dashboard</a>
  @else
      <a href="{{ route('login') }}">Log In</a>
  @endauth
  

• Inertia/Vue/React: Customize components in resources/js/Pages/Auth/. Example: Override Login component props:

  interface Props extends PageProps {
      status: string;
      canResetPassword: boolean;
      customField?: string; // Add custom prop
  }
  

4. Email Verification

• Enable in AuthServiceProvider:

  protected $policies = [
      'App\Models\User' => [VerifiesEmails::class],
  ];
  

• Customize verification email: Override resources/views/emails/verification.blade.php.

5. Password Confirmation

• Add to routes:

  Route::middleware(['auth', 'password'])->group(function () {
      // Routes requiring password confirmation
  });
  

• Customize confirmation view: resources/views/auth/confirm-password.blade.php.

Integration Tips

1. Database:

   • Breeze uses users table by default. Extend with migrations:

     php artisan make:migration add_custom_field_to_users_table --table=users
     

   • Update User model:

     protected $fillable = ['name', 'email', 'password', 'custom_field'];
     

2. Testing:

   • Use actingAs() in tests:

     $user = User::factory()->create();
     $this->actingAs($user);
     

   • Test frontend with Inertia/Vue/React test utilities.

3. API Stack:

   • For API-only apps, use breeze:install api to skip frontend assets.
   • Protect API routes with Sanctum:

     Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
         return $request->user();
     });
     

4. Customization:

   • Override default views/controllers by publishing assets:

     php artisan vendor:publish --tag=breeze-stubs
     

   • Extend styles: Add to resources/css/app.css (Tailwind).

Gotchas and Tips

Pitfalls

1. Middleware Conflicts:

   • Ensure auth middleware is not duplicated in route groups.
   • Fix: Use Route::middleware(['auth:sanctum', 'throttle:6,1']) instead of separate groups.

2. CSRF Token Mismatch:

   • Inertia/Vue/React apps may fail with CSRF errors if APP_URL is misconfigured.
   • Fix: Set APP_URL in .env to match your dev/prod domain.

3. Session Driver Issues:

   • Sanctum requires SESSION_DRIVER=file or database in .env.
   • Fix: Configure in .env:

     SESSION_DRIVER=file
     SANCTUM_STATEFUL_DOMAINS=localhost:3000
     

4. TypeScript Errors (Inertia/Vue/React):

   • Common causes: Missing @types or incorrect tsconfig.json.
   • Fix: Run npm install --save-dev @types/node and rebuild:

     npm run dev
     

5. Email Verification Loop:

   • Users stuck in verification loop if verified_at is not updated.
   • Fix: Check VerifyEmails trait and User model observers.

6. Tailwind Conflicts:

   • Custom CSS may override Breeze’s Tailwind classes.
   • Fix: Use !important sparingly; extend Tailwind config in tailwind.config.js:

     module.exports = {
         important: true,
         // ...
     }
     

Debugging Tips

1. Authentication Logs:

   • Enable Laravel debug mode:

     APP_DEBUG=true
     

   • Check storage/logs/laravel.log for auth failures.

2. Inertia/Vue/React Debugging:

   • Use Inertia.debug() in app/Http/Middleware/HandleInertiaRequests.php:

     public function share(Request $request): array
     {
         return array_merge(parent::share($request), [
             'appName' => config('app.name'),
             'debug' => app()->environment('local'),
         ]);
     }
     

   • Check browser console for SSR/CSR errors.

3. Database Seeding:

   • Reset migrations if users table is corrupted:

     php artisan migrate:fresh --seed
     

4. Sanctum Token Issues:

   • Clear Sanctum cache:

     php artisan sanctum:prune
     

   • Ensure SANCTUM_STATEFUL_DOMAINS includes all frontend domains.

Extension Points

1. Custom Auth Logic:

   • Override controllers:

     php artisan breeze:auth
     

   • Extend LoginController:

     public function authenticated(Request $request, $user)
     {
         // Custom logic (e.g., log activity)
         event(new Authenticated($request, $user));
     }
     

2. Multi-Factor Authentication (MFA):

   • Integrate with packages like laravel-2fa:

     composer require robinschmiedt/laravel-2fa
     

   • Extend User model:

     use RobinSchmiedt\TwoFactorAuth\Traits\TwoFactorAuthenticatable;
     

3. Socialite Providers:

   • Add GitHub/GitLab login:

     composer require laravel/socialite
     

   • Extend SocialAuthController:

     public function redirectToGitHub()
     {
         return Socialite::driver('github')->redirect();
     }
     

4. Custom User Model:

   • Extend User model:

     class User extends Authenticatable implements MustVerifyEmail
     {
         use HasApiTokens, HasFactory, Notifiable, TwoFactorAuthenticatable;
         // Custom traits/methods
     }
     

   • Update AuthServiceProvider:

     protected $model = \App\Models\User::class