Verify Email Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfonycasts/verify-email-bundle
   

   Add to config/bundles.php:

   Symfonycasts\VerifyEmailBundle\VerifyEmailBundle::class => ['all' => true],
   

2. Publish Config

   php bin/console make:verify-email
   

   This generates:

   • config/packages/verify_email.yaml (default config)
   • templates/verify_email/ (Twig templates)

3. First Use Case

   • For Users: Add verified_at column to your users table (migration provided via make:verify-email).
   • Trigger Verification: Use the VerifyEmailListener in your User entity:

     use Symfonycasts\VerifyEmailBundle\Message\SendVerificationEmailMessage;
     
     // In your registration controller/service
     $message = new SendVerificationEmailMessage($user);
     $this->messageBus->dispatch($message);
     

Key Files to Review

• Config: config/packages/verify_email.yaml (adjust from_email, success_path, failure_path).
• Templates: templates/verify_email/ (customize email/verification pages).
• Commands: php bin/console verify:email:resend (for testing).

Implementation Patterns

Common Workflows

1. User Registration Flow

// In your registration controller
public function register(Request $request, MessageBusInterface $bus)
{
    $user = User::create($request->all());
    $bus->dispatch(new SendVerificationEmailMessage($user));
    return redirect()->route('verification.notice'); // Default: /verify-email
}

2. Manual Verification Trigger

// Resend verification email (e.g., via user profile)
$bus->dispatch(new SendVerificationEmailMessage($user));

3. API Integration

// For API responses (e.g., Laravel Sanctum)
return response()->json([
    'message' => 'Verification email sent',
    'verification_url' => route('verify_email.verify', ['token' => $user->verificationToken])
]);

Integration Tips

Laravel-Specific Adjustments

1. Service Provider Binding (if not auto-discovered):

   // In AppServiceProvider
   $this->app->bind(
       Symfonycasts\VerifyEmailBundle\Message\SendVerificationEmailMessage::class,
       fn() => new SendVerificationEmailMessage($this->app['user'])
   );
   

2. Route Customization (override defaults):

   # config/packages/verify_email.yaml
   verify_email:
       success_path: '/account/verified' # Replace default
       failure_path: '/account/verification-failed'
   

3. Queue Integration (for async emails):

   // In config/packages/verify_email.yaml
   verify_email:
       send_email_in_background: true
   

Testing Patterns

• Unit Test Verification Logic:

  $this->bus->expects($this->once())
      ->method('dispatch')
      ->with(new SendVerificationEmailMessage($user));
  

• Feature Test Verification Flow:

  $response = $this->post('/register', $data);
  $response->assertRedirect('/verify-email');
  

Gotchas and Tips

Pitfalls

1. Token Expiration

   • Default token TTL: 24 hours (configurable via verify_email.token_ttl).
   • Fix: Extend TTL or implement a "resend" flow:

     verify_email:
         token_ttl: 7200 # 2 hours in seconds
     

2. Database Schema Mismatch

   • Error: Column 'verified_at' not found.
   • Fix: Run the migration generated by make:verify-email:

     php bin/console doctrine:migrations:execute --up
     

3. Email Delivery Issues

   • Symptom: Emails not sent in production.
   • Debug:
     • Check verify_email.send_email_in_background (set to false for debugging).
     • Verify from_email in config matches your SMTP setup.

4. Route Conflicts

   • Error: Route [verify_email.verify] not defined.
   • Fix: Ensure routes are loaded (check config/routes.yaml or web.php).

Debugging Tips

1. Log Verification Tokens Add to User entity:

   public function getVerificationToken(): ?string
   {
       return $this->verificationToken;
   }
   

2. Inspect Queued Jobs

   php bin/console debug:queue
   

3. Override Templates for Debugging Copy templates/verify_email/ to your project and add:

   {# templates/verify_email/verify_email.html.twig #}
   <pre>{{ dump(app('verify_email.token_generator').generateToken($user)) }}</pre>
   

Extension Points

1. Custom Token Generator

   // config/packages/verify_email.yaml
   verify_email:
       token_generator: App\Service\CustomTokenGenerator
   

2. Event Subscribers Listen for VerifyEmailEvents:

   use Symfonycasts\VerifyEmailBundle\Event\VerificationEmailSentEvent;
   
   public function onEmailSent(VerificationEmailSentEvent $event)
   {
       // Log or notify (e.g., Slack)
   }
   

3. API Responses Extend the VerifyEmailResponse class to customize JSON output:

   use Symfonycasts\VerifyEmailBundle\Response\VerifyEmailResponse;
   
   class CustomVerifyEmailResponse extends VerifyEmailResponse
   {
       public function toArray(): array
       {
           return [
               'status' => 'verification_sent',
               'data' => $this->getData(),
           ];
       }
   }
   

Pro Tips

1. Local Testing Use a local SMTP server (e.g., MailHog) and disable background processing:

   verify_email:
       send_email_in_background: false
   

2. Multi-Tenant Support Override token_generator to include tenant ID:

   public function generateToken(User $user): string
   {
       return hash('sha256', $user->email . $user->tenantId);
   }
   

3. Analytics Track verification clicks by extending the VerifyEmailController:

   public function verify(Request $request, TokenGeneratorInterface $tokenGenerator)
   {
       // Your analytics logic here
       return parent::verify($request, $tokenGenerator);
   }