ClouDNS Driver

Introduction

The ClouDNS Driver provides a fully typed interface for managing DNS zones and records via the ClouDNS API. It uses the Kipchak HTTP driver as its HTTP client, so no additional HTTP library is required.

Key features include:

• Multiple Connections: Configure separate credentials for multiple ClouDNS accounts.
• Fully Typed API: Dedicated request objects, result objects, and enums — your IDE will guide you through every call.
• Sub-account Support: Authenticate as a sub-user or sub-account in addition to the main account.
• Zone Management: List zones, retrieve zone info, and query page counts.
• DNS Record Management: List, retrieve, add, modify, and delete DNS records.
• All Record Types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, and all other types supported by ClouDNS.

Installation

Install the driver via Composer:

composer require kipchak/driver-cloudns

Initialise the Driver

Add the following to your drivers/drivers.php file. The ClouDNS driver depends on the Config and HTTP drivers, so it must be initialised after them:

use Kipchak\Driver\ClouDns\ClouDns;

ClouDns::initialise($container);

Configuration

Create a file named kipchak.cloudns.php in your project's config/ directory.

Connection Settings

Define one or more named connections under the connections key.

Authentication — supply exactly one of the following identity keys per connection:

The auth_password key is always required.

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    'connections' => [
        'default' => [
            'auth_id'       => env('CLOUDNS_AUTH_ID', ''),
            'auth_password' => env('CLOUDNS_AUTH_PASSWORD', ''),
        ],
        // Sub-account example:
        // 'reseller' => [
        //     'sub_auth_user' => env('CLOUDNS_SUB_USER', ''),
        //     'auth_password' => env('CLOUDNS_SUB_PASSWORD', ''),
        // ],
    ],
];

Environment Variables

CLOUDNS_AUTH_ID=your-auth-id
CLOUDNS_AUTH_PASSWORD=your-auth-password

Usage

Retrieve a connection by name. If no name is given, default is used.

use Kipchak\Driver\ClouDns\ClouDns;

$dns = ClouDns::get();            // 'default' connection
$dns = ClouDns::get('reseller');  // named connection

Zones

use Kipchak\Driver\ClouDns\Request\ListZonesRequest;

// List all zones — returns ZoneResult[]
$zones = $dns->listZones();

// Filter zones with optional parameters
$zones = $dns->listZones(new ListZonesRequest(
    page:        1,
    rowsPerPage: 20,
    search:      'example',
));

foreach ($zones as $zone) {
    echo $zone->name;          // 'example.com'
    echo $zone->type->value;   // 'master'
    echo $zone->status->value; // 1 (active)
}

// Get info for a specific zone — returns ZoneResult
$zone = $dns->getZoneInfo('example.com');

// Get total page count for pagination
$pages = $dns->getZonePageCount(rowsPerPage: 20);

Listing DNS Records

use Kipchak\Driver\ClouDns\Enum\DnsRecordType;
use Kipchak\Driver\ClouDns\Request\ListDnsRecordsRequest;

// List all records for a domain — returns DnsRecordResult[]
$records = $dns->listRecords('example.com');

// Filter by type and host
$records = $dns->listRecords('example.com', new ListDnsRecordsRequest(
    type: DnsRecordType::A,
    host: 'api',
));

foreach ($records as $record) {
    echo $record->id;         // 123456
    echo $record->type->value; // 'A'
    echo $record->host;       // 'api'
    echo $record->record;     // '192.0.2.1'
    echo $record->ttl;        // 3600
}

// Get a single record — returns DnsRecordResult
$record = $dns->getRecord('example.com', 123456);

Adding a DNS Record

use Kipchak\Driver\ClouDns\Enum\DnsRecordType;
use Kipchak\Driver\ClouDns\Request\AddDnsRecordRequest;

// A record
$dns->addRecord('example.com', new AddDnsRecordRequest(
    type:   DnsRecordType::A,
    host:   'api',
    ttl:    3600,
    record: '192.0.2.1',
));

// MX record (with priority)
$dns->addRecord('example.com', new AddDnsRecordRequest(
    type:     DnsRecordType::MX,
    host:     '',
    ttl:      3600,
    record:   'mail.example.com',
    priority: 10,
));

// SRV record (with priority, weight, port)
$dns->addRecord('example.com', new AddDnsRecordRequest(
    type:     DnsRecordType::SRV,
    host:     '_sip._tcp',
    ttl:      3600,
    record:   'sip.example.com',
    priority: 10,
    weight:   20,
    port:     5060,
));

Modifying a DNS Record

use Kipchak\Driver\ClouDns\Request\ModifyDnsRecordRequest;

// Only supply the fields you want to change
$dns->modifyRecord('example.com', 123456, new ModifyDnsRecordRequest(
    host:   'api',
    ttl:    300,
    record: '192.0.2.2',
));

Deleting a DNS Record

// Throws RuntimeException on failure; returns void on success
$dns->deleteRecord('example.com', 123456);

GeoDNS Records

GeoDNS records route visitors to different IPs based on their geographic location. They require a zone of type ZoneType::GeoDns. Location IDs and codes are available from the ClouDNS control panel or the list-geodns-locations API endpoint.

use Kipchak\Driver\ClouDns\Enum\DnsRecordType;
use Kipchak\Driver\ClouDns\Request\AddDnsRecordRequest;
use Kipchak\Driver\ClouDns\Request\ModifyDnsRecordRequest;

// Add a GeoDNS A record targeting European visitors
$dns->addRecord('example.com', new AddDnsRecordRequest(
    type:           DnsRecordType::A,
    host:           '@',
    ttl:            60,
    record:         '198.51.100.10',
    geodnsLocation: 7,      // ClouDNS location ID for Europe
    geodnsCode:     'EU',
));

// Add a GeoDNS A record targeting North American visitors
$dns->addRecord('example.com', new AddDnsRecordRequest(
    type:           DnsRecordType::A,
    host:           '@',
    ttl:            60,
    record:         '198.51.100.20',
    geodnsLocation: 1,
    geodnsCode:     'NA',
));

// Modify an existing GeoDNS record
$dns->modifyRecord('example.com', 654321, new ModifyDnsRecordRequest(
    host:           '@',
    ttl:            60,
    record:         '198.51.100.30',
    geodnsLocation: 7,
    geodnsCode:     'EU',
));

Type Reference

Enums

Request Objects

Result Objects

ZoneResult Properties

DnsRecordResult Properties

Error Handling

All methods throw a RuntimeException when the ClouDNS API returns a failed status. The message includes a [ClouDNS] prefix and the API's status description:

[ClouDNS] Invalid authentication.
[ClouDNS] Zone not found.

An InvalidArgumentException is thrown at construction time if auth_password is missing or no authentication identity (auth_id, sub_auth_id, or sub_auth_user) is provided.

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/drivers/cloudns.