Whois Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cwd/whois-bundle
   

   Enable the bundle in config/bundles.php (Symfony) or AppKernel.php (Laravel via Symfony bridge):

   // config/bundles.php
   return [
       // ...
       Cwd\WhoisBundle\CwdWhoisBundle::class => ['all' => true],
   ];
   

2. Basic Usage Inject the WhoisService into a controller or service:

   use Cwd\WhoisBundle\Service\WhoisService;
   
   class DomainController extends Controller
   {
       public function __construct(private WhoisService $whois)
       {
       }
   
       public function showWhois(string $domain)
       {
           $result = $this->whois->lookup($domain);
           return response()->json($result);
       }
   }
   

3. First Query Call the lookup() method with a domain name:

   $whoisData = $this->whois->lookup('example.com');
   

   Output will be a parsed array of WHOIS record data (e.g., registrant, expiry, nameservers).

Implementation Patterns

Common Workflows

1. Domain Validation Use WHOIS to validate domain ownership or registration status:

   $domain = 'example.com';
   $whois = $this->whois->lookup($domain);
   
   if (isset($whois['registrar']) && $whois['status'] === 'active') {
       // Domain is valid and active
   }
   

2. Expiry Date Checks Extract expiry dates for renewal reminders:

   $expiryDate = $whois['expiration_date'] ?? null;
   $daysUntilExpiry = Carbon::parse($expiryDate)->diffInDays();
   

3. Nameserver Lookup Fetch authoritative nameservers for DNS configuration:

   $nameservers = $whois['nameserver'] ?? [];
   

4. Batch Processing Process multiple domains efficiently (e.g., for bulk checks):

   $domains = ['example.com', 'test.org'];
   $results = collect($domains)->map(fn($d) => $this->whois->lookup($d));
   

Integration Tips

• Caching: Cache results for frequently queried domains (e.g., 24 hours):

  $whoisData = Cache::remember("whois_{$domain}", now()->addHours(24), fn() => $this->whois->lookup($domain));
  

• Rate Limiting: Implement throttling to avoid hitting WHOIS server limits:

  use Illuminate\Cache\RateLimiting\Limit;
  
  RateLimiter::for('whois', function () {
      return Limit::perMinute(10); // 10 requests/minute
  });
  

• Error Handling: Gracefully handle invalid domains or server errors:

  try {
      $whois = $this->whois->lookup($domain);
  } catch (\Exception $e) {
      return response()->json(['error' => 'WHOIS lookup failed'], 500);
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limits

   • Many WHOIS servers enforce strict rate limits (e.g., 1 request/second). Exceeding limits may result in temporary bans or IP blocking.
   • Fix: Use caching aggressively and implement exponential backoff for retries.

2. Inconsistent Data Formats

   • WHOIS records vary by TLD (e.g., .com vs .io). The bundle may not parse all fields uniformly.
   • Fix: Validate output structure and handle missing keys:

     $registrant = $whois['registrant'] ?? $whois['registrar'] ?? null;
     

3. Private Registration

   • Domains with private registration (e.g., via GoDaddy) may return generic WHOIS data.
   • Fix: Check for status: private or registrant: Redacted and handle accordingly.

4. Deprecated TLDs

   • Some TLDs (e.g., .info) have deprecated WHOIS services. Queries may fail silently.
   • Fix: Add a fallback mechanism or log failures for manual review.

5. Network Timeouts

   • WHOIS queries can time out for large domains or slow servers.
   • Fix: Increase timeout in the bundle’s config (if exposed) or use a retry decorator:

     $whois = new RetryableWhoisService($this->whois, 3); // Retry 3 times
     

Debugging

• Enable Verbose Output Check if the bundle supports debug mode (e.g., via config):

  # config/packages/cwd_whois.yaml
  verbose: true
  

• Raw WHOIS Data If parsing fails, inspect the raw response:

  $rawData = $this->whois->rawLookup($domain); // If method exists
  

Extension Points

1. Custom Parsers Extend the bundle’s parser for unsupported TLDs:

   use Cwd\WhoisBundle\Parser\WhoisParserInterface;
   
   class CustomWhoisParser implements WhoisParserInterface
   {
       public function parse(string $rawData): array
       {
           // Custom logic for TLD-specific parsing
       }
   }
   

   Register it in the bundle’s services.

2. Proxy Support Route WHOIS queries through a proxy for anonymity or compliance:

   # config/packages/cwd_whois.yaml
   proxy: http://your-proxy:port
   

3. Event Listeners Trigger actions on WHOIS events (e.g., expiry alerts):

   // In a service provider
   $this->app->make('events')->listen(
       \Cwd\WhoisBundle\Event\WhoisLookupEvent::class,
       function ($event) {
           // Handle event (e.g., log, notify)
       }
   );
   

4. Fallback Providers Implement a fallback to alternative WHOIS services (e.g., ARIN, RIPE) if the primary fails:

   $this->whois->setFallbackProvider(new ArinWhoisProvider());