Auth Email Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require baks-dev/auth-email in your Laravel project. Ensure your project meets the PHP 8.4+ requirement and has baks-dev/core and baks-dev/captcha installed (or update dependencies if missing).

2. Publish Assets & Migrations Execute:

   php artisan vendor:publish --provider="BaksDev\AuthEmail\AuthEmailServiceProvider"
   php artisan baks:assets:install
   php artisan migrate
   

   This sets up:

   • Database tables (e.g., auth_email_verification_tokens).
   • Views (e.g., login/registration templates in resources/views/auth-email/).
   • Config file (config/auth-email.php).

3. First Use Case: Email-Based Login Add the auth guard to config/auth.php:

   'guards' => [
       'web' => [
           'driver' => 'session',
           'provider' => 'email', // Use the email provider
       ],
   ],
   

   Use the LoginController (published with assets) or extend it:

   use BaksDev\AuthEmail\Http\Controllers\Auth\LoginController;
   

Implementation Patterns

Core Workflows

1. Email Verification Flow

   • Trigger Verification: After registration, call:

     $user->sendEmailVerificationNotification();
     

     (Extend BaksDev\AuthEmail\Notifications\VerifyEmail if needed.)
   • Token Handling: Tokens expire after 24h (configurable in auth-email.php). Verify via:

     Auth::guard('web')->verifyEmail($user);
     

2. Custom Login Logic

   • Override the default login logic in app/Http/Controllers/Auth/LoginController:

     public function login(Request $request)
     {
         $this->validate($request, [
             'email' => 'required|email',
             'password' => 'required',
             'captcha' => 'required|captcha', // Uses baks-dev/captcha
         ]);
         return $this->authenticate($request); // Uses AuthEmail guard
     }
     

3. Password Reset

   • Extend the default reset controller:

     use BaksDev\AuthEmail\Http\Controllers\Auth\ResetPasswordController;
     

   • Customize the reset email template by publishing views:

     php artisan vendor:publish --tag=auth-email-views
     

Integration Tips

• Laravel Fortify/Sanctum: Works alongside Fortify for API auth. Configure Sanctum to use the email provider:

  Sanctum::guard('web'); // Uses the email guard
  

• Multi-Guard Setups: Combine with Laravel’s default users provider:

  'providers' => [
      'email' => [
          'driver' => 'eloquent',
          'model' => \App\Models\User::class,
      ],
      'users' => [
          'driver' => 'eloquent',
          'model' => \App\Models\LegacyUser::class,
      ],
  ],
  

• Captcha Integration: Ensure baks-dev/captcha is configured in config/captcha.php for login/reset flows.

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • If baks-dev/core or baks-dev/captcha are outdated, the package may fail silently. Run:

     composer update baks-dev/core baks-dev/captcha
     

2. Token Expiry Issues

   • Tokens expire after 24h by default. Adjust in config/auth-email.php:

     'verification' => [
         'expire' => 60, // Minutes
     ],
     

   • Debugging: Check auth_email_verification_tokens table for stale tokens.

3. Locale/Translation Conflicts

   • Publish translations first:

     php artisan vendor:publish --tag=auth-email-lang
     

   • Override translations in resources/lang/{locale}/auth-email.php.

4. CSRF Token Mismatch

   • If using API routes, ensure VerifyCsrfToken middleware is excluded or configured for stateless APIs.

Debugging Tips

• Log Verification Events: Add to EventServiceProvider:

  protected $listen = [
      \BaksDev\AuthEmail\Events\VerificationAttempted::class => [
          \App\Listeners\LogVerificationAttempt::class,
      ],
  ];
  

• Check Middleware: Ensure VerifyEmail middleware is applied to protected routes:

  Route::middleware(['auth', 'verified'])->group(function () { ... });
  

Extension Points

1. Custom User Model Extend the default BaksDev\AuthEmail\Models\User or bind your model in AuthServiceProvider:

   public function boot()
   {
       Auth::provider('email', function ($app) {
           return new UserProvider($app['hash'], \App\Models\CustomUser::class);
       });
   }
   

2. Email Templates Override default Blade templates:

   • resources/views/auth-email/verify.blade.php
   • resources/views/auth-email/reset.blade.php

3. Rate Limiting Customize rate limits in app/Http/Middleware/ThrottleNodes:

   protected function limits()
   {
       return [
           'email-verification' => ['max' => 5, 'perMinute' => true],
       ];
   }
   

4. Two-Factor Auth (2FA) Integrate with Laravel’s two-factor package:

   use BaksDev\AuthEmail\Traits\TwoFactorAuth;
   class User extends Authenticatable {
       use TwoFactorAuth;
   }