Enom Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dekalee/enom
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="Dekalee\Enom\EnomServiceProvider"
   

2. Configuration

   • Set your API credentials in .env:

     ENOM_API_KEY=your_api_key_here
     ENOM_API_SECRET=your_api_secret_here
     ENOM_API_SANDBOX=false  # Set to true for testing
     

   • Verify the config file (config/enom.php) matches your needs.

3. First Use Case: Domain Registration

   use Dekalee\Enom\Enom;
   
   $enom = app(Enom::class);
   $domain = $enom->domains()->register('example.com', [
       'period' => 1, // 1-year registration
       'nameservers' => ['ns1.example.com', 'ns2.example.com'],
   ]);
   

4. Key Classes to Explore

   • Enom (Facade): Main entry point.
   • Domain (Resource): Represents domain objects.
   • Transfer (Resource): Handles domain transfers.
   • Contact (Resource): Manages registrant/contacts.

Implementation Patterns

Common Workflows

Domain Management

• Check Availability

  $available = $enom->domains()->check('example.com');
  

• Renew a Domain

  $domain = $enom->domains()->renew('example.com', 2); // Renew for 2 years
  

• Update Nameservers

  $domain = $enom->domains()->updateNameservers('example.com', [
      'ns1.example.com', 'ns2.example.com'
  ]);
  

Contact Management

• Create a Contact

  $contact = $enom->contacts()->create([
      'first_name' => 'John',
      'last_name' => 'Doe',
      'email' => 'john@example.com',
      'phone' => '+1234567890',
  ]);
  

• Assign Contact to Domain

  $domain = $enom->domains()->updateContact('example.com', 'registrant', $contact->id);
  

Transfers

• Initiate a Transfer

  $transfer = $enom->transfers()->initiate('example.com', [
      'auth_code' => 'ABC123', // EPP code
      'period' => 1,
  ]);
  

• Accept a Transfer

  $transfer = $enom->transfers()->accept($transfer->id);
  

Bulk Operations

• Use collections for batch processing:

  $domains = collect(['example.com', 'test.com']);
  $domains->each(fn($domain) => $enom->domains()->check($domain));
  

Integration Tips

1. Service Providers Bind the Enom facade in AppServiceProvider for cleaner usage:

   public function register()
   {
       $this->app->bind('enom', fn($app) => new Enom($app['config']['enom']));
   }
   

2. Event Handling Listen for domain events (if supported) to trigger workflows:

   Event::listen(DomainRegistered::class, function ($domain) {
       // Send welcome email, log activity, etc.
   });
   

3. API Rate Limiting Implement a queue for bulk operations to avoid hitting rate limits:

   foreach ($domains as $domain) {
       Queue::push(new RegisterDomainJob($domain));
   }
   

4. Testing Use the sandbox environment for tests:

   $this->app->singleton(Enom::class, fn() => new Enom([
       'sandbox' => true,
       'api_key' => 'test_key',
       'api_secret' => 'test_secret',
   ]));
   

Gotchas and Tips

Pitfalls

1. API Key Permissions

   • Ensure your API key has the correct permissions (e.g., Domain:Register, Contact:Create).
   • Test with a restricted key in sandbox first to avoid unexpected charges.

2. Sandbox vs. Production

   • Sandbox domains (e.g., example.com) may not be available for registration.
   • Use placeholder domains like sandbox123.com for testing.

3. Auth Codes for Transfers

   • Always verify the EPP auth code before initiating a transfer.
   • Store auth codes securely (e.g., encrypted in the database).

4. Rate Limits

   • Enom enforces rate limits (~10-20 requests/minute). Implement retries with exponential backoff:

     try {
         $domain = $enom->domains()->register('example.com', [...]);
     } catch (RateLimitExceededException $e) {
         sleep(10); // Wait and retry
         retry();
     }
     

5. Timeouts

   • API requests may time out for large operations (e.g., bulk DNS updates).
   • Increase PHP’s max_execution_time or use queues.

Debugging

1. Enable Debug Mode Set ENOM_DEBUG=true in .env to log raw API responses:

   ENOM_DEBUG=true
   

   Check logs in storage/logs/laravel.log.

2. Common Errors

   • InvalidDomain: Domain not available or invalid format. Fix: Validate domain format (e.g., Str::lower($domain)->contains('.')).
   • AuthenticationFailed: Incorrect API key/secret. Fix: Regenerate keys in Enom’s API settings.
   • InsufficientFunds: Account balance too low. Fix: Check balance via $enom->account()->balance().

3. Webhook Verification If using webhooks, verify the X-Enom-Signature header matches:

   $signature = hash_hmac('sha256', $payload, config('enom.webhook_secret'));
   if (!hash_equals($request->header('X-Enom-Signature'), $signature)) {
       abort(403);
   }
   

Extension Points

1. Custom Resources Extend the base Resource class to add domain-specific logic:

   class CustomDomain extends \Dekalee\Enom\Resources\Domain
   {
       public function addSsl()
       {
           return $this->callApi('POST', "/domains/{$this->id}/ssl");
       }
   }
   

2. Middleware for API Calls Add middleware to log or transform requests/responses:

   $enom->extend(function ($enom) {
       $enom->getMiddleware()->push(function ($request) {
           // Log request
           Log::debug('Enom API Call', ['url' => $request->url(), 'data' => $request->data()]);
       });
   });
   

3. Webhook Handlers Create a dedicated handler for Enom webhooks:

   class EnomWebhookHandler
   {
       public function handle($event, $payload)
       {
           match ($event) {
               'domain.registered' => $this->handleDomainRegistered($payload),
               default => Log::warning("Unhandled Enom event: {$event}"),
           };
       }
   }
   

4. Fallback for Missing Features Use Laravel’s HTTP client as a fallback for unsupported endpoints:

   $response = Http::withHeaders([
       'Authorization' => 'Basic ' . base64_encode(config('enom.api_key').':'.config('enom.api_secret')),
   ])->post('https://api.enom.com/xml/api', $xmlPayload);