Laravel Disposable Email Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require propaganistas/laravel-disposable-email
   

   The package auto-discovers its service provider—no manual registration needed.

2. Publish Config (optional but recommended for customization):

   php artisan vendor:publish --tag=laravel-disposable-email
   

   Config file: config/disposable-email.php.

3. First Use Case: Validate an email in a form request or controller:

   use Propaganistas\LaravelDisposableEmail\Rules\DisposableEmail;
   
   $request->validate([
       'email' => ['required', 'email', new DisposableEmail],
   ]);
   

Where to Look First

• Config File: config/disposable-email.php (blacklist sources, cache settings).
• Rule Class: Propaganistas\LaravelDisposableEmail\Rules\DisposableEmail (for customization).
• Tests: tests/ (for edge cases like subdomains or dynamic domains).

Implementation Patterns

Core Workflows

1. Form Validation:

   // In a FormRequest or controller
   $request->validate([
       'email' => [new DisposableEmail],
   ]);
   

   • Fails with: "The email field must not be a disposable email address."

2. Dynamic Validation (e.g., API responses):

   $validator = Validator::make($data, [
       'email' => [new DisposableEmail],
   ]);
   if ($validator->fails()) {
       return response()->json(['error' => $validator->errors()]);
   }
   

3. Customizing the Rule: Extend the rule for stricter/flexible checks:

   use Propaganistas\LaravelDisposableEmail\Rules\DisposableEmail as BaseDisposableEmail;
   
   class StrictDisposableEmail extends BaseDisposableEmail {
       protected $blacklistSources = ['disposable', 'custom_source'];
   }
   

Integration Tips

• Cache Blacklists: Enable caching in config to reduce API calls:

  'cache' => [
      'enabled' => true,
      'ttl' => 60 * 60, // 1 hour
  ],
  

• Queue Validation: Offload validation to a queue for long-running checks:

  $job = new ValidateDisposableEmail($email);
  dispatch($job);
  

• Localization: Add custom error messages in language files:

  'validation' => [
      'disposable_email' => 'This email is from a temporary service.',
  ],
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • Some legitimate domains (e.g., mail.me) may be flagged. Use allowlist in config to whitelist them:

     'allowlist' => ['mail.me', 'protonmail.com'],
     

   • Debugging: Temporarily disable the blacklist to test:

     'blacklist_sources' => [],
     

2. Dynamic Domains:

   • Services like temp-mail.org may use subdomains (e.g., abc123.temp-mail.org). The package handles this by default, but test thoroughly.

3. Rate Limits:

   • The default disposable/disposable API has rate limits. Cache aggressively or use a local mirror.

4. Case Sensitivity:

   • Email validation is case-insensitive, but the blacklist check is not. Normalize inputs:

     $email = strtolower($email);
     

Debugging

• Log Blacklist Hits: Add to DisposableEmail rule:

  protected function isDisposable($email) {
      $result = parent::isDisposable($email);
      \Log::debug("Disposable check for {$email}: " . ($result ? 'BLOCKED' : 'ALLOWED'));
      return $result;
  }
  

• Inspect Blacklist: Dump the loaded blacklist:

  \Log::info(config('disposable-email.blacklist'));
  

Extension Points

1. Custom Blacklist Sources: Add a new source (e.g., a local file or API):

   'blacklist_sources' => [
       'disposable', // Default
       'file://path/to/custom_blacklist.txt',
   ],
   

   • Supported formats: disposable, file://, https://.

2. Pre/Post-Validation Hooks: Override the rule’s passes() method:

   public function passes($attribute, $value) {
       if ($this->isDisposable($value)) {
           $this->addCustomMessage('custom_reason');
       }
       return !$this->isDisposable($value);
   }
   

3. Testing: Mock the blacklist in tests:

   $this->app->instance('disposable-email.blacklist', ['test@example.com']);