README

This API client is intended to be used with Technitiums DNS Server For the full Technitium API Documentation please visit Technitium API Documentation

Installation

Via Git

Run git clone https://github.com/ente/technitium-dnsserver-php-api.git where ever you want the library to be located.

Then require_once "/path/to/API.dnsserver.ente.php"; & use Technitium\DNSServer\API\API; in your PHP file.

Via Composer

Run composer require ente/technitium-dnsserver-php-api

Then: require_once "/path/to/vendor/autoload.php"; & use Technitium\DNSServer\API\API;

Configuration

.env

API_URL: The API URL of your Technitium DNS Server (with port), e.g. localhost:5380, 192.168.1.2:5380 or server.domain.tld:5380
USERNAME: The username for the user account. (You should create a dedicated one)
PASSWORD: The password for the user account.
INCLUDE_INFO: Returns basic information that might be relevant for the queried request.
TOKEN: Your API token, if already existent. ([Your Username] > [Create API Token]). If left empty, the API will use the username and password for authentication to create an API token for you and will write it to your .env.
USE_POST: Specify if you want to access the API via POST (true) instead of GET (false) in default.
USE_HTTPS: Enable (true) HTTPS for the API connection. If your server does not support HTTPS, the API will simply return false to all requests.

When using $api->admin()->logs()->export("2024-12-24") you may need to adjust the memory_limit in your php.ini file or via ini_set().

General Usage

require_once "/vendor/autoload.php";
use Technitium\DNSServer\API;

$api = new API("path/to/env", "env-name");

// Get all zones
$zones = $api->zones()->get();
// Get all zone records
$records = $api->zones()->records()->get("example.com");

// Install an app

$sampleApp = $api->apps()->listStoreApps()["storeApps"][0];
if($api->apps->install($sampleApp["name"])) {
    echo "App installed successfully!";
}

// OR

$sampleApp = $api->apps()->listStoreApps()["storeApps"][0];
if($api->apps->downloadAndInstall($sampleApp["name"], $sampleApp["url"])) {
    echo "App installed successfully!";
}

Send to custom endpoint

<?php

require_once "/vendor/autoload.php";
use Technitium\DNSServer\API;

$api = new API("path/to/env", "env-name");
// You have to set <bool>$bypass to true to use this feature
echo var_dump($api->sendCall(data: array("field" => "value"), endpoint: "admin/users/list", skip: false, bypass: true))

DDNS

You can use the DDNS.Helper.API.dnsserver.ente.php class to configure records to point to the current IP address.

<?php

require_once "/vendor/autoload.php";
use Technitium\DNSServer\API;
use Technitium\DNSServer\API\Helper\DDNS;

$path_to_configJSON = "/my/config.json";
$ddns = new DDNS(new API());
$ddns->updateRecords($path_to_configJSON);

// OR

$ddns_result = new DDNS(new API("path/to/env"), file_get_contents($path_to_configJSON)); // starts automatically updating the records

// OR
$api = new API();
$ddns_result = $api->ddns()->updateRecords($path_to_configJSON);

Your DDNS configuration file should look like this:

{
    "domanin": "example.com",
    "records": [
        "sub.example.com"
    ]
}

You can also set up multiple environments by using different configuration files:

<?php

require_once "/vendor/autoload.php";
use Technitium\DNSServer\API;
use Technitium\DNSServer\API\Helper\DDNS;

DDNS(new API("path/to/env"), file_get_contents("/my/config.json"));
DDNS(new API(__DIR__), file_get_contents("/my/config2.json"));
DDNS(new API(__DIR__ . "/configurations", ".env-custom"), file_get_contents("/my/config3.json"));

Changes

v1.2.1: Fixed and logs/export support

Added support for logs/export allowing you to export a DNS application log file
Fixed incorrect endpoint URL for some "Log" endpoints

v1.2: Adding support for export functions

Added support for export functions within API classes. When using export functions note that downloading log files may take quite a while. You may also need to adjust the memory_limit.

v1.1.4: Type safety

Added type safety to the DDNS.Helper.API.dnsserver.ente.php class
Added type safety to all other classes
Fixed incorrect/Added API docs

v1.1.3: Shell safe

Library is now shell safe (you are now required to specify the path to the .env file)
Silenced most $_SERVER['argv'] warnings when running the library in shell

v1.1.2: Quality

Added more documentation to the classes
Small code changes

v1.1.1: Fixes

Small changes to the README.md
Added code documentation within the classes
Implemented the <bool>$bypass parameter to the sendCall function to bypass the prepareEndpoint function therefore allowing to send to custom endpoints
Adjusted class functions scope

v1.1: Fixes

TOKEN can now be empty
Fixed some endpoints not working
Fixed issues preventing loading different environments
Exception handling

v1.0: Initial Release

initial release supporting each endpoint

ente / technitium-dnsserver-php-api

Maintainers

Details