enzonix/dns-sdk-php

PHP SDK for DNS Server Client API at Enzonix - Manage domains and DNS records with GeoDNS support

v1.0.0 2025-11-20 23:29 UTC

Requires

• php: >=7.4
• ext-curl: *
• ext-json: *

MIT

• Enzonix LLC

• api
• client
• sdk
• dns
• dns-server
• geodns
• enzonix

README

PHP SDK for interacting with the DNS Server Client API.

Installation

Install via Composer

composer require enzonix/dns-sdk-php

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension

Quick Start

<?php

use DNSServer\SDK\Client;
use DNSServer\SDK\Exceptions\APIException;

// Initialize the client
$client = new Client(
    'https://api.ns.enzonix.com',  // Base URL
    'your-api-token-here',         // API token
    30                             // Timeout in seconds (optional)
);

try {
    // List all domains
    $domains = $client->listDomains();
    foreach ($domains as $domain) {
        echo "Domain: {$domain->name} (ID: {$domain->id})\n";
    }
    
    // Create a new domain
    $domain = $client->createDomain('example.com');
    echo "Created domain: {$domain->name}\n";
    
    // Create a DNS record
    $record = $client->createRecord(
        $domain->id,
        'www',           // Record name
        'A',             // Record type
        '192.0.2.1',     // IP address
        3600,            // TTL (optional, default: 3600)
        0,               // Priority (optional, default: 0)
        ['disabled']     // Country codes (optional, default: ['disabled'])
    );
    echo "Created record: {$record->name} -> {$record->value}\n";
    
} catch (APIException $e) {
    echo "API Error: {$e->getMessage()} (HTTP {$e->getHttpCode()})\n";
}

API Reference

Client Methods

Domains

listDomains(): array

List all domains for the authenticated client.

Returns: Array of Domain objects

Example:

$domains = $client->listDomains();

createDomain(string $name): Domain

Create a new domain.

Parameters:

• $name (string): Domain name (e.g., "example.com")

Returns: Domain object

Example:

$domain = $client->createDomain('example.com');

deleteDomain(string $domainId): bool

Delete a domain.

Parameters:

• $domainId (string): UUID of the domain

Returns: true on success

Example:

$client->deleteDomain('123e4567-e89b-12d3-a456-426614174000');

Records

listRecords(string $domainId): array

List all DNS records for a domain.

Parameters:

• $domainId (string): UUID of the domain

Returns: Array of Record objects

Example:

$records = $client->listRecords($domain->id);

createRecord(...): Record

Create a new DNS record.

Parameters:

• $domainId (string): UUID of the domain
• $name (string): Record name (e.g., "www" or "@" for root)
• $type (string): Record type (A, AAAA, CNAME, MX, TXT, etc.)
• $value (string): Record value
• $ttl (int, optional): TTL in seconds (default: 3600)
• $priority (int, optional): Priority for MX records (default: 0)
• $countryCodes (array, optional): Country codes for GeoDNS (default: ["disabled"])

Returns: Record object

Example:

// A record
$record = $client->createRecord(
    $domain->id,
    'www',
    'A',
    '192.0.2.1'
);

// MX record
$mxRecord = $client->createRecord(
    $domain->id,
    '@',
    'MX',
    'mail.example.com.',
    3600,
    10
);

// GeoDNS record (US only)
$geoRecord = $client->createRecord(
    $domain->id,
    'www',
    'A',
    '192.0.2.2',
    3600,
    0,
    ['US']
);

// SRV record
$srvRecord = $client->createRecord(
    $domain->id,
    '_sip._tcp',                    // Service name (format: _service._protocol)
    'SRV',
    '5060 sipserver.example.com.',  // Value format: port target
    3600,                            // TTL
    10                               // Priority
);

updateRecord(...): Record

Update an existing DNS record.

Parameters: Same as createRecord(), but first parameter is $recordId instead of $domainId

Returns: Updated Record object

Example:

$updated = $client->updateRecord(
    $record->id,
    'www',
    'A',
    '192.0.2.2'  // New IP address
);

deleteRecord(string $recordId): bool

Delete a DNS record.

Parameters:

• $recordId (string): UUID of the record

Returns: true on success

Example:

$client->deleteRecord($record->id);

BIND Zone Files

importBIND(string $zoneContent): array

Import a BIND zone file.

Parameters:

• $zoneContent (string): BIND zone file content

Returns: Array containing:

• domain: Domain object
• records_created: Number of records created
• records: Array of created Record objects
• errors (optional): Array of error messages if partial success

Example:

$zoneContent = file_get_contents('example.com.zone');
$result = $client->importBIND($zoneContent);
echo "Created {$result['records_created']} records\n";

exportBIND(string $domainId): string

Export a domain as a BIND zone file.

Parameters:

• $domainId (string): UUID of the domain

Returns: BIND zone file content as string

Example:

$zoneContent = $client->exportBIND($domain->id);
file_put_contents('example.com.zone', $zoneContent);

Nameserver Management

checkNameserver(string $domainId): array

Check nameserver configuration for a domain.

Parameters:

• $domainId (string): UUID of the domain

Returns: Array containing:

• domain: Updated Domain object
• check: Array with valid (bool) and status (string)

Example:

$result = $client->checkNameserver($domain->id);
if ($result['check']['valid']) {
    echo "Nameservers are correctly configured\n";
} else {
    echo "Nameserver check status: {$result['check']['status']}\n";
}

API Key Management

rotateAPIKey(): Client

Rotate/regenerate the API key for the authenticated client.

Returns: Updated Client object with new API token

Example:

$updatedClient = $client->rotateAPIKey();
echo "New API token: {$updatedClient->apiToken}\n";
// Update your client instance with the new token
$client = new Client($baseUrl, $updatedClient->apiToken);

Models

Domain

Properties:

• id (string): UUID
• clientId (string): Client UUID
• name (string): Domain name
• active (bool): Whether domain is active
• createdAt (string): Creation timestamp
• updatedAt (string): Last update timestamp
• nameserverLastCheckedAt (string|null): Last nameserver check time
• nameserverVerifiedAt (string|null): When nameservers were verified
• nameserverCheckStatus (string|null): Nameserver check status

Record

Properties:

• id (string): UUID
• domainId (string): Domain UUID
• name (string): Record name
• type (string): Record type (A, AAAA, CNAME, MX, etc.)
• ttl (int): TTL in seconds
• countryCodes (array): Country codes for GeoDNS
• priority (int): Priority (for MX records)
• value (string): Record value
• createdAt (string): Creation timestamp
• updatedAt (string): Last update timestamp

Client

Properties:

• id (string): UUID
• name (string): Client name
• email (string): Client email
• apiToken (string): API token
• domainLimit (int): Maximum number of domains
• createdAt (string): Creation timestamp
• updatedAt (string): Last update timestamp

Error Handling

All API methods throw APIException on failure. The exception includes:

• Error message
• HTTP status code (accessible via getHttpCode())

Example:

try {
    $domain = $client->createDomain('example.com');
} catch (APIException $e) {
    switch ($e->getHttpCode()) {
        case 400:
            echo "Bad request: {$e->getMessage()}\n";
            break;
        case 401:
            echo "Unauthorized: Invalid API token\n";
            break;
        case 403:
            echo "Forbidden: {$e->getMessage()}\n";
            break;
        case 404:
            echo "Not found: {$e->getMessage()}\n";
            break;
        case 409:
            echo "Conflict: Domain already exists\n";
            break;
        default:
            echo "Error ({$e->getHttpCode()}): {$e->getMessage()}\n";
    }
}

GeoDNS Support

The DNS server supports GeoDNS routing based on country codes. When creating or updating records:

• ["disabled"] or []: Record is returned to all requests (no GeoDNS)
• ["US"]: Record is only returned for US requests
• ["US", "CA", "MX"]: Record is returned for North America region

Example:

// Default record (all locations)
$default = $client->createRecord(
    $domain->id,
    'www',
    'A',
    '192.0.2.1',
    3600,
    0,
    ['disabled']
);

// US-specific record
$usRecord = $client->createRecord(
    $domain->id,
    'www',
    'A',
    '192.0.2.2',
    3600,
    0,
    ['US']
);

// EU region
$euRecord = $client->createRecord(
    $domain->id,
    'www',
    'A',
    '192.0.2.3',
    3600,
    0,
    ['DE', 'FR', 'NL', 'BE']
);

License

MIT

Support

For issues and questions, please open an issue on GitHub.