Transip Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require dopee/transip-api-bundle
   

2. Register the Bundle Add to config/bundles.php (Laravel 5.4+):

   Dopee\TransipApiBundle\TransipApiBundle::class => ['env' => env('APP_ENV') !== 'production'],
   

   (Note: Laravel uses config/bundles.php instead of AppKernel.php.)

3. Configure Parameters Add to .env:

   TRANSIP_LOGIN=yourusername
   TRANSIP_PRIVATE_KEY="yourmultilinekeywithoutbreaks"
   TRANSIP_READONLY=true
   TRANSIP_ENDPOINT=https://api.transip.nl
   

4. Publish Config (Optional) Publish the default config:

   php artisan vendor:publish --provider="Dopee\TransipApiBundle\TransipApiServiceProvider"
   

   (Laravel uses vendor:publish instead of Symfony’s config:dump.)

5. First Use Case Inject the client into a service/controller:

   use Dopee\TransipApiBundle\Client\TransipClientInterface;
   
   public function __construct(TransipClientInterface $transipClient) {
       $this->transipClient = $transipClient;
   }
   

   Fetch domains:

   $domains = $this->transipClient->getDomains();
   

Implementation Patterns

Common Workflows

1. Domain Management

   • Fetch all domains:

     $domains = $this->transipClient->getDomains();
     

   • Create a domain:

     $this->transipClient->createDomain([
         'name' => 'example.com',
         'nameservers' => ['ns1.example.com', 'ns2.example.com'],
     ]);
     

   • Update DNS records:

     $this->transipClient->updateDnsRecords('example.com', [
         ['name' => 'www', 'type' => 'A', 'content' => '192.0.2.1'],
     ]);
     

2. SSL Certificates

   • List certificates:

     $certificates = $this->transipClient->getSslCertificates();
     

   • Request a certificate:

     $this->transipClient->requestSslCertificate('example.com', [
         'csr' => '-----BEGIN CERTIFICATE REQUEST-----...',
     ]);
     

3. Service Integration

   • Event Listeners: Trigger actions on domain events (e.g., renewal).

     $this->transipClient->on('domainRenewal', function ($domain) {
         // Send email notification
     });
     

   • Cron Jobs: Schedule periodic checks (e.g., SSL expiry).

     $this->transipClient->checkSslExpiry('example.com');
     

4. Error Handling Wrap API calls in a try-catch:

   try {
       $this->transipClient->getDomain('example.com');
   } catch (\Dopee\TransipApiBundle\Exception\TransipException $e) {
       Log::error('TransIP API Error: ' . $e->getMessage());
   }
   

Laravel-Specific Tips

1. Service Provider Binding Bind the client to Laravel’s container in AppServiceProvider:

   public function register() {
       $this->app->bind(TransipClientInterface::class, function ($app) {
           return new \Dopee\TransipApiBundle\Client\TransipClient(
               $app['config']['transip_api.login'],
               $app['config']['transip_api.private_key'],
               $app['config']['transip_api.read_only'],
               $app['config']['transip_api.endpoint']
           );
       });
   }
   

2. Configuration Management Use Laravel’s config() helper to access settings:

   $login = config('transip_api.login');
   

3. Artisan Commands Create a custom command to interact with TransIP:

   use Illuminate\Console\Command;
   use Dopee\TransipApiBundle\Client\TransipClientInterface;
   
   class TransipDomainCommand extends Command {
       protected $transipClient;
   
       public function __construct(TransipClientInterface $transipClient) {
           parent::__construct();
           $this->transipClient = $transipClient;
       }
   
       public function handle() {
           $domains = $this->transipClient->getDomains();
           $this->info('Domains: ' . json_encode($domains));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Private Key Formatting

   • The private key must be a single-line string (no newlines or spaces).
   • If copied from TransIP’s UI, remove all breaks:

     // Wrong (multiline)
     $key = "-----BEGIN PRIVATE KEY-----
     MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
     -----END PRIVATE KEY-----";
     
     // Correct (single-line)
     $key = "-----BEGIN PRIVATE KEY-----MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...-----END PRIVATE KEY-----";
     

2. Read-Only Mode

   • If read_only: true, all write operations (e.g., createDomain, updateDnsRecords) will fail with a TransipException.
   • Test in read_only: false first, then switch to true for production.

3. Rate Limiting

   • TransIP’s API has rate limits. Cache responses aggressively:

     $domains = Cache::remember('transip_domains', 300, function () {
         return $this->transipClient->getDomains();
     });
     

4. Deprecation Warnings

   • The bundle is Symfony2-focused and lacks Laravel-specific features (e.g., no make:transip-command).
   • Some methods may return raw arrays instead of Laravel collections. Convert with:

     collect($rawData)->toArray();
     

5. Endpoint Overrides

   • For testing, override the endpoint in .env:

     TRANSIP_ENDPOINT=https://api.transip.eu  # EU endpoint
     

Debugging Tips

1. Enable API Logging Add this to config/services.php:

   'transip_api' => [
       'debug' => env('APP_DEBUG', false),
   ],
   

   Then check Laravel’s log for raw API responses.

2. Mocking the Client Use Laravel’s Mockery for testing:

   $mock = Mockery::mock(TransipClientInterface::class);
   $mock->shouldReceive('getDomains')->andReturn(['example.com']);
   
   $this->app->instance(TransipClientInterface::class, $mock);
   

3. Common Errors

   • Authentication Failed: Verify the private key and login.
   • Invalid Request: Check JSON payload structure (TransIP is strict about formatting).
   • SSL Certificate Error: Ensure the endpoint uses https://.

Extension Points

1. Custom API Methods Extend the client by creating a decorator:

   class CustomTransipClient implements TransipClientInterface {
       protected $decorated;
   
       public function __construct(TransipClientInterface $client) {
           $this->decorated = $client;
       }
   
       public function getDomainsWithExpiry() {
           $domains = $this->decorated->getDomains();
           return collect($domains)->map(function ($domain) {
               $domain['expiry'] = now()->addDays(30)->toDateString(); // Example
               return $domain;
           });
       }
   
       // Delegate all other methods to $this->decorated
       public function __call($method, $args) {
           return call_user_func_array([$this->decorated, $method], $args);
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(TransipClientInterface::class, function ($app) {
       return new CustomTransipClient($app->make(TransipClient::class));
   });
   

2. Event Dispatching Trigger Laravel events for TransIP actions:

   $this->transipClient->createDomain($data);
   event(new DomainCreated($data));
   

3. Queueable Jobs Offload long-running operations (e.g., DNS bulk updates) to