Email Check Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require voku/email-check
   

   Add to composer.json if using a monorepo or constrained environment.

2. Basic Usage

   use Voku\EmailCheck\EmailCheck;
   
   $email = 'test@example.com';
   $result = EmailCheck::check($email);
   
   // Result structure:
   // [
   //   'valid' => bool,
   //   'reason' => string|null,
   //   'syntax' => bool,
   //   'dns' => bool,
   //   'disposable' => bool,
   //   'trash' => bool,
   //   'typo' => bool,
   //   'suggestions' => array,
   // ]
   

3. First Use Case Validate user input in a registration form:

   $request->validate([
       'email' => ['required', function ($attribute, $value, $fail) {
           $result = EmailCheck::check($value);
           if (!$result['valid']) {
               $fail('Invalid email: ' . ($result['reason'] ?? 'unknown error'));
           }
       }]
   ]);
   

Implementation Patterns

Common Workflows

1. Bulk Validation

   $emails = ['user1@example.com', 'invalid@test'];
   $results = EmailCheck::checkMultiple($emails);
   // Returns array of result objects
   

2. Async Validation (Queue Jobs)

   // Dispatch a job for DNS-heavy checks
   EmailCheckJob::dispatch($email)->onQueue('email-validation');
   

3. Integration with Laravel Forms

   // Custom rule for form requests
   use Illuminate\Validation\Rule;
   
   $request->validate([
       'email' => [
           'required',
           Rule::custom(function ($value) {
               return EmailCheck::check($value)['valid'];
           })
       ]
   ]);
   

4. Caching Results

   // Cache DNS checks for 24h
   $cacheKey = "email:{$email}:dns";
   if (Cache::has($cacheKey)) {
       $result['dns'] = Cache::get($cacheKey);
   } else {
       $result['dns'] = EmailCheck::checkDNS($email);
       Cache::put($cacheKey, $result['dns'], now()->addHours(24));
   }
   

Advanced Patterns

1. Custom Suggestion Logic

   $result = EmailCheck::check($email);
   if ($result['typo']) {
       $suggestions = EmailCheck::getSuggestions($email);
       // Integrate with frontend for autocomplete
   }
   

2. Disposable Email Blocking

   if (EmailCheck::isDisposable($email)) {
       return back()->withErrors('Disposable emails not allowed.');
   }
   

3. Rate Limiting DNS Checks

   // Throttle DNS queries to avoid abuse
   $throttleKey = "email:dns:{$email}";
   if (!RateLimiter::tooManyRequests($throttleKey, 10)) {
       $result['dns'] = EmailCheck::checkDNS($email);
   }
   

Gotchas and Tips

Pitfalls

1. DNS Check Timeouts

   • Default DNS checks can block requests. Use checkDNS($email, 2) to limit timeout (seconds).
   • Fix: Offload to a queue or use a shorter timeout.

2. False Positives for Trash Emails

   • checkTrash() may flag legitimate emails as "trash" if the domain is misconfigured.
   • Fix: Combine with checkDNS() for accuracy:

     $result['trash'] = EmailCheck::checkDNS($email) && EmailCheck::checkTrash($email);
     

3. Disposable Email Lists

   • The package’s disposable list may not cover all providers.
   • Fix: Extend with a custom list:

     EmailCheck::addDisposableDomains(['mailinator.com', 'tempmail.com']);
     

4. Case Sensitivity

   • EmailCheck::check() normalizes case, but some DNS checks may not.
   • Fix: Normalize input:

     $email = strtolower($email);
     

Debugging Tips

1. Verbose Output

   $result = EmailCheck::check($email, true); // Enable debug mode
   dd($result); // Inspect all checks
   

2. DNS-Specific Errors

   • Use checkDNS() separately to isolate issues:

     try {
         $dnsResult = EmailCheck::checkDNS($email);
     } catch (\Exception $e) {
         // Log or handle DNS failure gracefully
     }
     

3. Performance Profiling

   • DNS checks are the slowest. Profile with:

     $start = microtime(true);
     $result = EmailCheck::check($email);
     $time = microtime(true) - $start;
     // Log $time for optimization
     

Extension Points

1. Custom Check Logic

   // Add a custom validation rule
   EmailCheck::addCheck('custom', function ($email) {
       return str_contains($email, 'corp') && str_ends_with($email, 'company.com');
   });
   

2. Override Default Providers

   • Replace the disposable email list:

     EmailCheck::setDisposableDomainsFile('/path/to/custom_list.txt');
     

3. Mocking for Tests

   // In PHPUnit tests
   EmailCheck::setMockDNS(true); // Disable real DNS checks
   EmailCheck::setMockDNSResult($email, true); // Force pass/fail
   

4. Laravel Service Provider Bind the package to the container for dependency injection:

   $this->app->singleton(EmailCheck::class, function () {
       return new EmailCheck();
   });