Easyname Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require cwd/easyname-php-sdk
   

2. Initialize the Client:

   use Cwd\Easyname\Client;
   
   $client = new Client('your_api_key', 'your_api_secret');
   

3. First Use Case: Fetch Domain Availability

   $result = $client->domains()->checkAvailability('example.com');
   if ($result->isAvailable()) {
       echo "Domain is available!";
   }
   

Key Starting Points

• API Reference: Easyname DevBlog (official docs).
• Client Methods: Explore Client class methods (e.g., domains(), contacts(), orders()).
• Error Handling: Review Cwd\Easyname\Exception for API response errors.

Implementation Patterns

Core Workflows

1. Domain Management

   • Check Availability:

     $client->domains()->checkAvailability('test.com');
     

   • Register/Transfer:

     $client->domains()->register('test.com', [
         'period' => 1, // years
         'nameservers' => ['ns1.example.com', 'ns2.example.com']
     ]);
     

   • List Domains:

     $domains = $client->domains()->listDomains();
     

2. Contact Management

   • Create/Update Contact:

     $client->contacts()->create([
         'firstName' => 'John',
         'lastName' => 'Doe',
         'email' => 'john@example.com'
     ]);
     

   • Assign to Domain:

     $client->domains()->setContact('test.com', $contactId);
     

3. Order Management

   • Place Order:

     $client->orders()->create([
         'domain' => 'test.com',
         'contactId' => $contactId,
         'period' => 1
     ]);
     

   • List Orders:

     $client->orders()->listOrders();
     

Integration Tips

• Rate Limiting: The SDK handles retries for HTTP 429 (Too Many Requests). Customize via:

  $client = new Client('key', 'secret', [
      'retry_after' => 5, // seconds
  ]);
  

• Webhooks: Use Cwd\Easyname\Webhook to listen for domain events (e.g., renewal, expiration).

  $webhook = new Webhook('webhook_secret');
  $webhook->handle($_POST); // Verify and process payloads
  

• Caching Responses: Cache domain availability checks (TTL: 5 minutes) to reduce API calls:

  $cacheKey = "domain_availability:test.com";
  if (Cache::has($cacheKey)) {
      return Cache::get($cacheKey);
  }
  $result = $client->domains()->checkAvailability('test.com');
  Cache::put($cacheKey, $result, now()->addMinutes(5));
  

Gotchas and Tips

Common Pitfalls

1. Deprecated PHP Version:

   • The SDK requires PHP ≥ 5.3, but modern Laravel (8+) uses PHP ≥ 7.4. Test thoroughly if using older PHP versions.
   • Fix: Upgrade PHP or use a compatibility layer like php-compat.

2. API Key Permissions:

   • Missing or incorrect API keys/secrets return 401 Unauthorized. Double-check:

     try {
         $client->domains()->checkAvailability('test.com');
     } catch (Cwd\Easyname\Exception\UnauthorizedException $e) {
         // Log or alert: Invalid credentials
     }
     

3. Nameserver Validation:

   • Easyname enforces minimum 2 nameservers for registration. Omitting them triggers:

   $client->domains()->register('test.com', []); // Throws ValidationException
   

   Fix: Always include nameservers in registration payloads.

4. Webhook Verification:

   • Webhook payloads must be verified with the webhook_secret. Skipping this exposes your endpoint to spoofing.

   $webhook->handle($_POST); // Throws InvalidSignatureException if invalid
   

Debugging Tips

• Enable Debug Mode:

  $client = new Client('key', 'secret', [
      'debug' => true, // Logs raw API requests/responses
  ]);
  

  Check Laravel logs (storage/logs/laravel.log) for raw API interactions.

• Mocking the SDK for Tests: Use Laravel’s Mockery to isolate API calls:

  $mockClient = Mockery::mock('Cwd\Easyname\Client');
  $mockClient->shouldReceive('domains->checkAvailability')
             ->once()
             ->andReturn(new Cwd\Easyname\Response\DomainAvailability(true));
  

Extension Points

1. Custom Response Handling: Extend Cwd\Easyname\Response\AbstractResponse to add domain-specific logic:

   class CustomDomainResponse extends AbstractResponse {
       public function isPremium() {
           return $this->data['is_premium'] ?? false;
       }
   }
   

2. Add New API Endpoints: The SDK follows a resource-based pattern (domains(), contacts()). Add new resources by extending Cwd\Easyname\Resource\AbstractResource:

   class Invoices extends AbstractResource {
       public function listInvoices() {
           return $this->request('GET', '/invoices');
       }
   }
   

   Register it in the Client class:

   public function invoices() {
       return new Invoices($this);
   }
   

3. Override HTTP Client: Replace the default Guzzle client for custom headers/timeout:

   $client = new Client('key', 'secret', [
       'http_client' => new CustomGuzzleClient([
           'timeout' => 30,
           'headers' => ['X-Custom-Header' => 'value']
       ]),
   ]);