Enom Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require dekalee/enom-bundle to add the package to your Laravel project. Register the service provider in config/app.php under providers:

   Dekalee\EnomBundle\EnomServiceProvider::class,
   

   Publish the config file (if needed) with:

   php artisan vendor:publish --provider="Dekalee\EnomBundle\EnomServiceProvider" --tag="config"
   

2. Configuration Add your Enom API credentials to .env:

   ENOM_USERNAME=your_username
   ENOM_PASSWORD=your_password
   ENOM_SANDBOX=false
   

   The bundle expects these keys by default (verify via config/enom.php after publishing).

3. First Use Case Inject the EnomClient into a service or controller:

   use Dekalee\EnomBundle\Client\EnomClient;
   
   public function __construct(EnomClient $enomClient) {
       $this->enomClient = $enomClient;
   }
   

   Test a basic domain lookup:

   $domainInfo = $this->enomClient->getDomainInfo('example.com');
   

Implementation Patterns

Core Workflows

1. Domain Management

   • Registration: Use createDomain() with required parameters (e.g., period, nameservers).

     $this->enomClient->createDomain([
         'domain' => 'example.com',
         'period' => 1, // Years
         'nameservers' => ['ns1.example.com', 'ns2.example.com'],
     ]);
     

   • Renewal: Call renewDomain() with the domain name and period.

     $this->enomClient->renewDomain('example.com', 2); // Renew for 2 years
     

   • Transfers: Handle inbound/outbound transfers via transferDomain() and acceptTransfer().

     $this->enomClient->transferDomain('example.com', 'authCode123');
     

2. DNS Management Leverage the getDnsRecords() and updateDnsRecords() methods for dynamic DNS updates:

   $records = $this->enomClient->getDnsRecords('example.com');
   $this->enomClient->updateDnsRecords('example.com', [
       ['type' => 'A', 'name' => 'www', 'address' => '192.0.2.1'],
   ]);
   

3. Event-Driven Integrations Use the EnomEvents facade to listen for domain lifecycle events (e.g., DomainRenewalFailed):

   use Dekalee\EnomBundle\Events\EnomEvents;
   
   EnomEvents::listen('DomainRenewalFailed', function ($event) {
       Log::error("Renewal failed for {$event->domain}", $event->data);
   });
   

4. Bulk Operations For large-scale actions (e.g., renewing 100+ domains), batch requests using batchDomains():

   $domains = ['example1.com', 'example2.com'];
   $this->enomClient->batchDomains($domains, 'renew', ['period' => 1]);
   

Integration Tips

• Queue Delayed Tasks: Wrap long-running operations (e.g., bulk transfers) in Laravel queues:

  dispatch(new RenewDomainsJob(['example1.com', 'example2.com'], 1));
  

• Cache Responses: Cache domain info for 5 minutes to reduce API calls:

  $domainInfo = Cache::remember("enom:domain:example.com", 300, function () {
      return $this->enomClient->getDomainInfo('example.com');
  });
  

• Fallback Logic: Implement retry logic for transient failures (e.g., rate limits):

  try {
      $this->enomClient->renewDomain('example.com', 1);
  } catch (EnomException $e) {
      if ($e->getCode() === 429) {
          sleep(10);
          retry();
      }
      throw $e;
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Silent failures if ENOM_USERNAME/ENOM_PASSWORD are missing or incorrect.
   • Fix: Validate credentials early via a health check route:

     Route::get('/enom/health', function (EnomClient $client) {
         try {
             $client->getAccountInfo();
             return response()->json(['status' => 'healthy']);
         } catch (Exception $e) {
             return response()->json(['error' => $e->getMessage()], 500);
         }
     });
     

2. Sandbox Mode Quirks

   • Issue: Sandbox mode (ENOM_SANDBOX=true) may return mock data that doesn’t match production behavior.
   • Fix: Test critical paths in both modes before going live.

3. Rate Limiting

   • Issue: Enom’s API enforces rate limits (~100 requests/minute). Bulk operations may hit these.
   • Fix: Implement exponential backoff in your retry logic:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $this->enomClient->batchDomains(...);
             break;
         } catch (RateLimitException $e) {
             $attempts++;
             sleep(2 ** $attempts);
         }
     }
     

4. Deprecated Methods

   • Issue: The underlying dekalee/enom library may change method signatures without major version bumps.
   • Fix: Pin the dekalee/enom package to a specific version in composer.json:

     "require": {
         "dekalee/enom": "1.0.0"
     }
     

Debugging

• Enable Verbose Logging: Set ENOM_DEBUG=true in .env to log raw API responses.
• Inspect Exceptions: Catch Dekalee\EnomBundle\Exception\EnomException for detailed error messages:

  catch (EnomException $e) {
      Log::error('Enom Error: ' . $e->getMessage(), [
          'code' => $e->getCode(),
          'response' => $e->getResponse(),
      ]);
  }
  

Extension Points

1. Custom Responses Transform API responses using a decorator pattern:

   $client->setResponseTransformer(function ($response) {
       return collect($response)->map(function ($item) {
           $item['formatted_price'] = '$' . $item['price'];
           return $item;
       });
   });
   

2. Webhook Handlers Extend the EnomWebhookHandler to process Enom’s push notifications:

   class CustomWebhookHandler extends EnomWebhookHandler {
       protected function handleDomainRenewal($data) {
           // Custom logic (e.g., update CRM)
       }
   }
   

   Register it in EnomServiceProvider:

   $this->app->bind(EnomWebhookHandler::class, CustomWebhookHandler::class);
   

3. Mocking for Tests Use Laravel’s Mockery to stub the EnomClient in unit tests:

   $mock = Mockery::mock(EnomClient::class);
   $mock->shouldReceive('getDomainInfo')
        ->with('example.com')
        ->andReturn(['status' => 'active']);
   
   $this->app->instance(EnomClient::class, $mock);