Email Verification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cyrilbras/email_verification_bundle
   

   Add the bundle to config/bundles.php:

   Cyrilbras\EmailVerificationBundle\EmailVerificationBundle::class => ['all' => true],
   

2. Publish Config:

   php artisan vendor:publish --provider="Cyrilbras\EmailVerificationBundle\EmailVerificationServiceProvider" --tag="config"
   

   Edit config/email_verification.php to configure:

   • verification_url (e.g., route('email.verify'))
   • expiry_minutes (default: 60)
   • resend_limit (e.g., 3 attempts)
   • mailer (e.g., mail or ses)

3. First Use Case: Trigger verification for a user in a controller:

   use Cyrilbras\EmailVerificationBundle\Services\EmailVerificationService;
   
   public function register(Request $request, EmailVerificationService $verifier)
   {
       $user = User::create($request->validated());
       $verifier->sendVerificationEmail($user);
       return redirect()->route('home');
   }
   

4. Verify Route: Add to routes/web.php:

   Route::get('/email/verify/{token}', [EmailVerificationController::class, 'verify'])->name('email.verify');
   

Implementation Patterns

Core Workflow

1. Sending Verification Emails:

   • Use EmailVerificationService to send tokens via:

     $verifier->sendVerificationEmail($user, ['custom' => 'data']);
     

   • Customize email templates by publishing views:

     php artisan vendor:publish --tag="email_verification_views"
     

     Override resources/views/vendor/email_verification/email.blade.php.

2. Handling Verification:

   • The verify() method in EmailVerificationController automatically:
     • Validates the token.
     • Marks the user as verified (is_verified = true).
     • Redirects with success/error messages.
   • Extend logic by overriding the controller or using events:

     // In EventServiceProvider
     protected $listen = [
         'Cyrilbras\EmailVerificationBundle\Events\VerificationAttempted' => [
             'App\Listeners\LogVerificationAttempt',
         ],
     ];
     

3. Resending Emails:

   • Allow users to resend via a route:

     Route::post('/email/resend', [EmailVerificationController::class, 'resend'])->name('email.resend');
     

   • Check resend limits in config/email_verification.php.

4. Token Management:

   • Tokens are stored in the email_verification_tokens table (auto-created).
   • Regenerate tokens manually:

     $verifier->regenerateToken($user);
     

Integration Tips

• Laravel Notifications: Replace the default mailer with a Notification class:

  use Cyrilbras\EmailVerificationBundle\Notifications\VerifyEmail;
  
  // In your controller
  $user->notify(new VerifyEmail($user));
  

• Multi-Tenant: Scope tokens to tenants by adding a tenant_id column to the tokens table and filtering queries in the service.

• Testing: Use EmailVerificationService directly in tests:

  $verifier->shouldReceive('sendVerificationEmail')->once();
  

Gotchas and Tips

Pitfalls

1. Token Expiry:

   • Tokens expire after expiry_minutes (default: 60). Ensure this aligns with your UX (e.g., shorter for sensitive actions).
   • Debug expired tokens with:

     SELECT * FROM email_verification_tokens WHERE created_at < NOW() - INTERVAL '60 MINUTE';
     

2. Database Migrations:

   • The bundle creates a email_verification_tokens table. If you customize the table name in config, run:

     php artisan vendor:publish --tag="migrations"
     

     Then modify the published migration.

3. Rate Limiting:

   • Resend limits are enforced via the resend_limit config. Bypass cautiously in tests:

     $verifier->setResendLimit(10); // Temporarily override
     

4. Token Collisions:

   • Tokens are UUIDs, but ensure your User model’s getEmailForVerification() method returns the correct email to avoid mismatches.

Debugging

• Log Verification Events: Listen for VerificationAttempted and VerificationFailed events to debug:

  event(new VerificationAttempted($user, $token));
  

• Token Validation: Manually validate a token:

  $verifier->validateToken($token); // Returns bool
  

• Email Delivery: Use Laravel’s Mail::fake() to test emails:

  Mail::fake();
  $verifier->sendVerificationEmail($user);
  Mail::assertSent(VerifyEmail::class);
  

Extension Points

1. Custom Token Storage: Override the TokenRepository interface to use Redis or another store:

   $service->setTokenRepository(new RedisTokenRepository());
   

2. Dynamic Verification URLs: Customize the verification URL per user:

   $verifier->sendVerificationEmail($user, ['url' => route('email.verify', ['tenant' => $tenant])]);
   

3. Multi-Factor Verification: Combine with packages like laravel-fortify by triggering verification after registration:

   event(new Registered($user));
   $verifier->sendVerificationEmail($user);
   

4. Webhook Verification: Replace the verify() route with a webhook endpoint for API-driven apps:

   Route::post('/api/verify', [EmailVerificationController::class, 'webhookVerify']);