Phone Verification Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beelab/phone-verification-bundle
   

   Add to config/bundles.php:

   BeeLab\PhoneVerificationBundle\BeeLabPhoneVerificationBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console bee-lab:phone-verification:install
   

   Edit config/packages/bee_lab_phone_verification.yaml to set:

   • service (Twilio, Nexmo, etc.)
   • API credentials
   • Default country code

3. First Use Case Verify a phone number in a controller:

   use BeeLab\PhoneVerificationBundle\Service\PhoneVerificationService;
   
   class UserController extends AbstractController
   {
       public function verifyPhone(PhoneVerificationService $verifier)
       {
           $verifier->sendVerificationCode('+1234567890');
           // Returns a UUID for tracking
       }
   }
   

Implementation Patterns

Workflow: User Phone Verification

1. Trigger Verification

   $verifier->sendVerificationCode($phoneNumber);
   // Returns UUID (e.g., 'a1b2c3d4')
   

   Store the UUID in the user session or DB.

2. Verify Code

   $verifier->verifyCode($phoneNumber, $userSubmittedCode, $uuid);
   // Returns bool
   

3. Resend Code

   $verifier->resendCode($phoneNumber, $uuid);
   

Integration Tips

• Symfony Forms: Bind to a form field and validate with a custom constraint:

  use BeeLab\PhoneVerificationBundle\Validator\Constraints\PhoneVerification;
  
  #[PhoneVerification(message: 'Invalid verification code')]
  public $verificationCode;
  

• Event Listeners: Extend functionality via events:

  # config/packages/bee_lab_phone_verification.yaml
  listeners:
      BeeLab\PhoneVerificationBundle\EventListener\YourCustomListener: ['onVerificationSent']
  

• Async Processing: Use Symfony Messenger to decouple verification logic:

  $verifier->sendVerificationCodeAsync($phoneNumber);
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • Twilio/Nexmo impose limits (e.g., 1 SMS/minute). Handle RateLimitExceededException:

     try {
         $verifier->sendVerificationCode($phone);
     } catch (RateLimitExceededException $e) {
         $this->addFlash('error', 'Please wait before retrying.');
     }
     

   • Tip: Implement a retry queue for failed sends.

2. UUID Management

   • The bundle generates UUIDs for tracking. Never reuse UUIDs for the same phone number.
   • Tip: Store UUIDs in the DB with a used_at timestamp to auto-cleanup old entries.

3. Timeouts

   • Verification codes expire after verification_code_lifetime (default: 10 minutes).
   • Tip: Show a countdown in the UI to avoid user frustration.

4. International Numbers

   • Ensure phone numbers are formatted with country codes (e.g., +447123456789).
   • Tip: Use libphonenumber to validate/normalize numbers before passing to the bundle.

Debugging

• Logs: Enable debug mode in config/packages/bee_lab_phone_verification.yaml:

  debug: true
  

  Logs appear in var/log/dev.log.

• Test Mode: Simulate sends without actual SMS:

  test_mode: true
  

  Useful for development/testing.

Extension Points

1. Custom Services Override the default service (e.g., for a custom SMS provider):

   services:
       BeeLab\PhoneVerificationBundle\Service\PhoneVerificationService:
           arguments:
               $smsService: '@your.custom.sms_service'
   

2. Templates Customize SMS templates by extending the bundle’s twig templates:

   {# templates/bee_lab_phone_verification/verification_code.txt.twig #}
   Your verification code is: {{ code }}. Valid for {{ lifetime }} minutes.
   

3. Validation Extend the PhoneVerification constraint to add custom rules:

   class CustomPhoneVerification extends PhoneVerification
   {
       public $message = 'Custom error message.';
   }
   

Config Quirks

• Default Country Code: Set in config to avoid manual prefixing:

  default_country_code: '+1'  # US
  

• Environment Variables: Use %env() for credentials:

  twilio:
      account_sid: '%env(TWILIO_SID)%'
      auth_token: '%env(TWILIO_TOKEN)%'
  

• Caching: Disable if using async processing to avoid race conditions:

  cache_verification_codes: false