NetDNS2

https://github.com/mikepultz/netdns2
Admin
NetDNS2 is a pure PHP DNS Resolver and Updater library that offers local caching, dynamic DNS...
Tokens:111,519
Snippets:752
Trust Score:5.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Cache Factory Usage Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/cache.md

Example of creating a file-based cache instance and performing put and get operations.

```php
$cache = \NetDNS2\Cache::factory(\NetDNS2\Cache::CACHE_TYPE_FILE, [
    'file' => '/tmp/cache.txt',
    'size' => 50000,
    'ttl_override' => 300,
]);
$cache->put('key', $response);            // \NetDNS2\Packet\Response
$cached = $cache->get('key');             // \NetDNS2\Packet\Response|false
```

--------------------------------

### NetDNS2 Data Usage Examples

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/data.md

Examples demonstrating domain, IPv4, IPv6, RR assignment, and IDN round-trip handling.

```php
$d = new \NetDNS2\Data\Domain(\NetDNS2\Data::DATA_TYPE_RFC1035, 'example.com');
echo $d;                      // example.com
echo $d->value();             // example.com

$ip = new \NetDNS2\Data\IPv4('93.184.216.34');
echo $ip;                     // 93.184.216.34
$ip6 = new \NetDNS2\Data\IPv6('::1');
echo $ip6;                    // ::1

// RR assignment auto-converts to the declared Data type
$mx = \NetDNS2\RR::fromString('example.com 300 IN MX 10 mail.example.com');
echo $mx->exchange;           // mail.example.com (Data\Domain)
$s = strval($mx->exchange);   // explicit cast when a string is required

// IDN round-trip (requires ext-intl)
$idn = new \NetDNS2\Data\Domain(\NetDNS2\Data::DATA_TYPE_RFC1035, '域名.中国');
echo $idn;                    // xn--eqrt2g.xn--fiqs8s (Punycode on the wire)
echo $idn->value();           // 域名.中国 (decoded for display)
```

--------------------------------

### Question Usage Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/question.md

Demonstrates manual creation of a Question object and accessing properties from a packet request.

```php
$q = new \NetDNS2\Question();
$q->qname  = new \NetDNS2\Data\Domain(\NetDNS2\Data::DATA_TYPE_RFC1035, 'example.com');
$q->qtype  = \NetDNS2\ENUM\RR\Type::set('MX');
$q->qclass = \NetDNS2\ENUM\RR\Classes::set('IN');

echo $q;   // ";;\n;; Question:\n;;\t example.com. MX IN"

// typical wire usage via a packet
$req = new \NetDNS2\Packet\Request('example.com');
$question = $req->question[0];
printf("qname=%s qtype=%s qclass=%s\n",
    $question->qname,
    $question->qtype->label(),
    $question->qclass->label());
```

--------------------------------

### Notifier Constructor Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/notifier.md

Initializes a new Notifier instance for a specific zone with optional client configuration.

```php
$n = new \NetDNS2\Notifier('netdns2.com', [ 'nameservers' => [ '192.168.0.1' ]]);
```

--------------------------------

### Typical Socket Usage Pattern

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/socket.md

Example demonstrating the standard workflow of opening a socket, writing data, and reading the response.

```php
$sock = new \NetDNS2\Socket(\NetDNS2\Socket::SOCK_DGRAM, '1.1.1.1', 53, 5.0);
if ($sock->open() === false) {
    throw new \RuntimeException($sock->last_error);
}
if ($sock->write($packet_data) === false) {
    throw new \RuntimeException($sock->last_error);
}
$size = 0;
$data = $sock->read($size, \NetDNS2\Header::DNS_MAX_UDP_SIZE);
if ($data === false) {
    throw new \RuntimeException($sock->last_error);
}
```

--------------------------------

### Install NetDNS2 via Composer

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Use this command to install the NetDNS2 library as a dependency in your PHP project.

```bash
composer require mikepultz/netdns2
```

--------------------------------

### Update Lease with Updater

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/edns.md

Example showing how to use the Updater class to update a lease with EDNS options.

```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->edns->update_lease(true, time(), 0);
$u->update();
```

--------------------------------

### Initialize NetDNS2 Resolver with configuration array

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/configuration.md

Example of instantiating a new \NetDNS2\Resolver with a full set of configuration options provided as an associative array.

```php
$r = new \NetDNS2\Resolver([
    'nameservers'           => [ '1.1.1.1', '8.8.8.8' ],
    'ns_random'             => true,
    'timeout'               => 0.05,
    'use_tcp'               => false,
    'use_tls'               => false,
    'tls_context'           => [ 'verify_peer' => true ],
    'dns_port'              => -1,
    'local_host'            => '',
    'local_port'            => 0,
    'domain'                => '',
    'cache_type'            => \NetDNS2\Cache::CACHE_TYPE_NONE,
    'cache_options'         => [],
    'strict_query_mode'     => false,
    'recurse'               => true,
    'dnssec'                => false,
    'dnssec_ad_flag'        => false,
    'dnssec_cd_flag'        => false,
    'dnssec_payload_size'   => 4000,
]);
```

--------------------------------

### Enable Multiple EDNS Options

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/edns.md

Example showing how to enable several different EDNS options before performing a DNS query.

```php
$r = new \NetDNS2\Resolver([ 'nameservers' => [ '192.168.0.1' ]]);

$r->edns->client_subnet(true, '10.10.10.0/24');
$r->edns->tcp_keepalive(true, 300);
$r->edns->nsid(true);
$r->edns->dau(true, [ 9, 10, 16 ]);
$r->edns->cookie(true, '3132333435363738');

$res = $r->query('example.com', 'A');
```

--------------------------------

### Staged update with prerequisites and error handling

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/updater.md

Example demonstrating how to configure an updater, add prerequisites, perform an update, and handle potential exceptions.

```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', '9dnf93asdf39fs');

$u->checkNotExists('test.example.com', 'A');           // prerequisite
$u->add(\NetDNS2\RR::fromString('test.example.com 600 IN A 2.2.2.2'));

try {
    $u->update();
    echo "update OK\n";
} catch (\NetDNS2\Exception $e) {
    printf("update failed (code %d): %s\n", $e->getCode(), $e->getMessage());
    if ($e->getResponse() !== null) {
        echo "server rcode: " . $e->getResponse()->header->rcode->label() . "\n";
    }
}
```

--------------------------------

### Header Usage Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/header.md

Demonstrates creating a custom header, packing it into a request, and parsing a header from an existing packet.

```php
$h = new \NetDNS2\Header();            // default query header
$h->rd = 0;                            // no recursion
$h->opcode = \NetDNS2\ENUM\OpCode::UPDATE;
// pack into a packet
$p = new \NetDNS2\Packet\Request('example.com');
// 'Resolver' would normally do this for you; direct use:
try {
    $parsed = new \NetDNS2\Header($some_packet);
    echo $parsed->rcode->label();      // e.g. "The request completed successfully."
} catch (\NetDNS2\Exception $e) {
    echo "invalid header: " . $e->getMessage();
}
```

--------------------------------

### Example: Configuring Name Servers

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/client.md

Demonstrates how to set name servers using an array of IP addresses and DoH URLs, or by loading configuration from a resolv.conf file.

```php
$r = new \NetDNS2\Resolver();
$r->setServers([ '1.1.1.1', 'https://cloudflare-dns.com/dns-query' ]);

// or load from a file
$r->setServers('/etc/resolv.conf');
```

--------------------------------

### NetDNS2\RR::fromString() usage examples

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr.md

Examples showing how to parse various DNS record types from strings, including handling of invalid input.

```php
$a   = \NetDNS2\RR::fromString('test.example.com 600 IN A 2.2.2.2');
$mx  = \NetDNS2\RR::fromString('example.com. 3600 IN MX 10 mail.example.com.');
$txt = \NetDNS2\RR::fromString('example.com 300 IN TXT "hello world" "second string"');
$ds  = \NetDNS2\RR::fromString('. 0 IN DS 20326 8 2 E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D');

try {
    $bad = \NetDNS2\RR::fromString('only two tokens');
} catch (\NetDNS2\Exception $e) {
    // 'failed to parse config: minimum of name, type and rdata required.'
}
```

--------------------------------

### Get MX Records for a Domain

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of querying and iterating through MX records for google.com.

```php
try
{
	//
	// create new resolver object, passing in an array of name servers to use for lookups
	//
	$r = new \NetDNS2\Resolver(['nameservers' => [ '1.1.1.1' ]]);

	//
	// execute the query request for the google.com MX servers
	//
	$res = $r->query('google.com', 'MX');

	//
	// loop through the answer, printing out the MX servers returned.
	//
	foreach($res->answer as $mxrr)
	{
		printf("preference=%d, host=%s\n", $mxrr->preference, $mxrr->exchange);
	}

} catch(\NetDNS2\Exception $e)
{
	echo "::query() failed: " . $e->getMessage() . "\n";
}
```

--------------------------------

### Private-zone trust anchor example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/dnssec-validator.md

Example showing how to add a custom trust anchor for a private zone using a DS or DNSKEY record.

```APIDOC
## Example: Private-zone trust anchor

### Description
Demonstrates adding a custom trust anchor for a private zone using a DS record or a DNSKEY record.

### Code
```php
$v = new \NetDNS2\DNSSEC\Validator($r);
$v->addTrustAnchor(\NetDNS2\RR::fromString(
    'internal. 0 IN DS 12345 8 2 <hex-digest>'
));
// or a DNSKEY (converted to a synthetic DS automatically)
$v->addTrustAnchor(\NetDNS2\RR\DNSKEY::fromString(
    'internal. 0 IN DNSKEY 257 3 8 AwEAA...'
));
```
```

--------------------------------

### BIND Configuration for TSIG

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example BIND configuration for a zone allowing updates and transfers using a TSIG key.

```text
key "mykey" {
    algorithm hmac-sha256;
    secret "9dnf93asdf39fs";
};

zone "example.com" {
    type master;
    file "dynamic/example.com";

    allow-transfer {
        key "mykey";
    }

    allow-update {
        key "mykey";
    };
};
```

--------------------------------

### Standard validation flow example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/dnssec-validator.md

Example showing how to validate a DNS response using the root trust anchor.

```APIDOC
## Example: Standard validation flow

### Description
Demonstrates setting up a resolver with DNSSEC enabled, creating a Validator, installing the root trust anchor, and validating a query response.

### Code
```php
try {
    $r = new \NetDNS2\Resolver([ 'nameservers' => [ '1.1.1.1' ]]);
    $r->dnssec = true;

    $v = new \NetDNS2\DNSSEC\Validator($r);
    $v->useRootTrustAnchor();

    $res = $r->query('example.com', 'A');
    $v->validate($res);

    echo "signature chain verified successfully\n";

} catch (\NetDNS2\Exception $e) {
    printf("DNSSEC validation failed (code %d): %s\n", $e->getCode(), $e->getMessage());
}
```
```

--------------------------------

### Example usage of iquery()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/resolver.md

Demonstrates how to perform an inverse query by creating an RR object and passing it to the iquery method within a try-catch block.

```php
try {
    $rr = \NetDNS2\RR::fromString('example.com 300 IN A 93.184.216.34');
    $res = $r->iquery($rr);
} catch (\NetDNS2\Exception $e) {
    // likely "DNS request failed: The name server does not support the requested kind of query."
}
```

--------------------------------

### Notifier notify() Full Flow Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/notifier.md

Demonstrates a complete notify workflow including TSIG signing, adding an SOA record, and handling potential exceptions.

```php
try {
    $n = new \NetDNS2\Notifier('netdns2.com', [ 'nameservers' => [ '192.168.0.1' ]]);
    $n->signTSIG('mykey', '9dnf93asdf39fs');
    $n->add(\NetDNS2\RR::fromString('netdns2.com 3600 IN SOA ns1.netdns2.com hostmaster.netdns2.com 2024010101 7200 3600 1209600 300'));

    $response = null;
    $n->notify($response);

    if ($response !== null) {
        echo "notify OK from " . $response->answer_from . "\n";
    }
} catch (\NetDNS2\Exception $e) {
    printf("notify failed (code %d): %s\n", $e->getCode(), $e->getMessage());
    if ($e->getRequest() !== null) {
        // inspect the packet that failed
        echo $e->getRequest()->header;
    }
}
```

--------------------------------

### useRootTrustAnchor Method

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/dnssec-validator.md

Installs the built-in IANA root-zone trust anchors (KSK-2017 and KSK-2024).

```php
public function useRootTrustAnchor(): void
```

--------------------------------

### Setting Resolver Properties After Initialization

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of setting resolver properties directly on the object instance after initialization.

```php
$r = new \NetDNS2\Resolver();

$r->timeout = 1.5;
$r->dnssec = true;

$res = $r->query('google.com', 'A');
```

--------------------------------

### Example - Signed update records

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr-types.md

Demonstrates how to sign a dynamic DNS update using the Updater class and the TSIG class with HMAC_SHA256.

```APIDOC
## Example - Signed update records

### Description
Demonstrates how to sign a dynamic DNS update using the Updater class and the TSIG class with HMAC_SHA256.

### Code
```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', '9dnf93asdf39fs', \NetDNS2\RR\TSIG::HMAC_SHA256);
$u->add(\NetDNS2\RR::fromString('test.example.com 600 IN A 2.2.2.2'));
$u->update();
```
```

--------------------------------

### useRootTrustAnchor()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/dnssec-validator.md

Installs the built-in IANA root-zone trust anchors (KSK-2017 and KSK-2024) for validation.

```APIDOC
## useRootTrustAnchor()

### Description
Installs the built-in IANA root-zone trust anchors from root-anchors.xml: KSK-2017 (key tag 20326) and KSK-2024 (key tag 38696), both RSASHA256/SHA-256 DS records.

### Method
useRootTrustAnchor

### Signature
public function useRootTrustAnchor(): void

### Throws
- \NetDNS2\Exception - Only via RR::fromString() on malformed anchor data (not expected for built-ins).
```

--------------------------------

### Reading record fields

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr.md

Example demonstrating how to iterate through DNS query results and access type-specific fields like IPv4 addresses.

```php
$res = $r->query('google.com', 'A');
foreach ($res->answer as $rr) {
    // guard for type-specific fields
    if ($rr->type == \NetDNS2\ENUM\RR\Type::A) {
        echo $rr->address;          // Data\IPv4 (Stringable)
    }
}
```

--------------------------------

### Constructing a DNS Request

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/packet.md

Example of creating a new request, attaching additional resource records, and updating the header count.

```php
$req = new \NetDNS2\Packet\Request('example.com', 'MX', 'IN');
$wire = $req->get();                       // binary packet
$req->additional[] = $tsig_rr;             // attach extra RRs before get()
$req->header->arcount = count($req->additional);
```

--------------------------------

### signSIG0() usage

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/client.md

Installs SIG(0) authentication using a private key file. This method requires the openssl extension and supports specific RSA algorithms.

```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signSIG0('/etc/named/Kexample.com.+008+15765.private');
$u->update();
```

--------------------------------

### Header get() Method

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/header.md

Packs the header into a 12-byte binary string and advances the packet offset by 12 bytes.

```php
public function get(\NetDNS2\Packet &$_packet): string
```

--------------------------------

### signSIG0()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/client.md

Installs SIG(0) authentication (RFC 2931) from a dnssec-keygen private key file, or from an existing RR\SIG object. Only RSA algorithms are supported (RSAMD5, RSASHA1, RSASHA256, RSASHA512). Requires ext-openssl.

```APIDOC
## signSIG0()

### Description
Installs SIG(0) authentication (RFC 2931) from a dnssec-keygen private key file, or from an existing RR\SIG object. Only RSA algorithms are supported (RSAMD5, RSASHA1, RSASHA256, RSASHA512). Requires ext-openssl.

### Method
signSIG0

### Signature
public function signSIG0(\NetDNS2\RR\SIG|string $_filename): bool

### Parameters
- **$_filename** (\NetDNS2\RR\SIG|string) - Required - Path to a K<name>.+<alg>+<tag>.private file, or a pre-built RR\SIG object

### Returns
bool - true

### Throws
\NetDNS2\Exception
- ENUM\Error::INT_INVALID_EXTENSION - openssl extension not loaded.
- ENUM\Error::INT_INVALID_ALGORITHM - key algorithm is not one of the four RSA algorithms (DSA deliberately unsupported).
- Propagates PrivateKey::parseFile() errors (INT_INVALID_PRIVATE_KEY, INT_FAILED_OPENSSL, ...).

### Example
```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signSIG0('/etc/named/Kexample.com.+008+15765.private');
$u->update();
```
```

--------------------------------

### Error handling on creation

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr.md

Example demonstrating how to catch exceptions when creating an RR object with an invalid record type.

```php
try {
    $rr = \NetDNS2\RR::fromString('example.com 300 IN NOEXISTTYPE 1.2.3.4');
} catch (\NetDNS2\Exception $e) {
    printf("parse failure code=%d: %s\n", $e->getCode(), $e->getMessage());
}
```

--------------------------------

### Perform a Simple A Record Lookup

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of performing a simple A record lookup for facebook.com using a specific nameserver.

```php
try
{
	//
	// create new resolver object, passing in an array of name servers to use for lookups
	//
	$r = new \NetDNS2\Resolver(['nameservers' => [ '1.1.1.1' ]]);

	//
	// execute the query
	//
	$res = $r->query('facebook.com', 'A');

	//
	// if facebook points to more than one IP, then you can loop through the answer array to
	// see each IP address.
	//
	echo "facebook resolves to: " . $res->answer[0]->address;

} catch(\NetDNS2\Exception $e)
{
	echo "::query() failed: " . $e->getMessage() . "\n";
}
```

--------------------------------

### Configure Resolver with File Cache

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/cache.md

Example of initializing a NetDNS2 Resolver with file-based caching enabled. The cache_options array defines the file path, maximum cache size, and a TTL override.

```php
$r = new \NetDNS2\Resolver([
    'nameservers'   => [ '192.168.0.1' ],
    'cache_type'    => \NetDNS2\Cache::CACHE_TYPE_FILE,
    'cache_options' => [ 'file' => '/tmp/cache.txt', 'size' => 50000, 'ttl_override' => 300 ],
]);

$res = $r->query('example.com', 'A');   // cached on second call
```

--------------------------------

### BitMap Usage Example

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/bitmap.md

Demonstrates validating an array of RR types, converting to a bitmap, and parsing it back. Also shows how NSEC RRs access type bit maps.

```php
$labels = \NetDNS2\BitMap::validateArray([ 1, 'AAAA', 'TYPE65534' ]);
// ['A', 'AAAA', 'TYPE65534']

$bitmap = \NetDNS2\BitMap::arrayToBitMap($labels);
$roundtrip = \NetDNS2\BitMap::bitMapToArray($bitmap);

// NSEC/NSEC3 RRs use this internally:
$nsec = \NetDNS2\RR::fromString('example.com 300 IN NSEC next.example.com A AAAA MX RRSIG NSEC');
foreach ($nsec->type_bit_maps as $t) {
    echo $t . "\n";
}
```

--------------------------------

### Enable DNS over TLS (DoT) with NetDNS2 Resolver

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Sets use_tls to true to enable DoT, changing the default port to 853 and using TCP. Requires the OpenSSL extension. The example queries facebook.com for an A record and prints the first answer address.

```php
try
{
    //
    // create new resolver object, passing in an array of name servers to use for lookups
    //
    $r = new \NetDNS2\Resolver(['nameservers' => [ '1.1.1.1' ]]);

    //
    // enable DoT
    //
    $r->use_tls = true;

    //
    // execute the query request for the google.com MX servers
    //
    $res = $r->query('facebook.com', 'A');

    //
    // if facebook points to more than one IP, then you can loop through the answer array to
    // see each IP address.
    //
    echo "facebook resolves to: " . $res->answer[0]->address;

} catch(\NetDNS2\Exception $e)
{
    echo "::query() failed: " . $e->getMessage() . "\n";
}
```

--------------------------------

### Perform IPv6 Forward DNS Lookup (AAAA)

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Query an AAAA record for a domain name. The example shows the query and the resulting output.

```php
$res = $r->query('a2.test.com', 'AAAA');

a2.test.com. 86400 IN AAAA ff01:0:0:0:0:0:0:43
```

--------------------------------

### get()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr.md

Encodes common fields and calls rrGet(). Skips RDATA when rdlength is -1. For OPT types, packs udp_length in the class field and calls pre_build().

```APIDOC
## get()

### Description
Encodes common fields and calls rrGet(). Skips RDATA when rdlength is -1. For OPT types, packs udp_length in the class field and calls pre_build().

### Method
get

### Signature
public function get(\NetDNS2\Packet &$_packet): string

### Parameters
- **$_packet** (\NetDNS2\Packet) - Required - The packet to encode the record into.

### Return Value
- **string** - The encoded record string.
```

--------------------------------

### Initialize Resolver with custom options

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/resolver.md

Demonstrates how to instantiate the Resolver class with specific nameservers and configure properties like timeout and DNSSEC after initialization.

```php
$r = new \NetDNS2\Resolver([ 'nameservers' => [ '1.1.1.1', '8.8.8.8' ]]);
$r->timeout = 1.5;
$r->dnssec  = true;   // properties can be set after construction
```

--------------------------------

### signTSIG() usage

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/client.md

Installs a TSIG RR to authenticate outgoing requests. The example shows both default HMAC-SHA256 and custom HMAC-SHA512 algorithm usage.

```php
$r = new \NetDNS2\Resolver([ 'nameservers' => [ '192.168.0.1' ]]);
$r->signTSIG('mykey', '9dnf93asdf39fs');                 // HMAC-SHA256 (default)
$r->signTSIG('mykey', '9dnf93asdf39fs', \NetDNS2\RR\TSIG::HMAC_SHA512);
```

--------------------------------

### Direct PrivateKey instantiation

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/private-key.md

Demonstrates loading a private key file directly to access its properties like keytag, algorithm, and signer name.

```php
try {
    $priv = new \NetDNS2\PrivateKey('/etc/named/Kexample.com.+008+15765.private');
    printf("keytag=%d algorithm=%s signer=%s\n",
        $priv->keytag, $priv->algorithm->label(), $priv->signname);
} catch (\NetDNS2\Exception $e) {
    echo "failed to load key: " . $e->getMessage() . "\n";
}
```

--------------------------------

### Catching NetDNS2\Exception

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/exception.md

Example of how to catch NetDNS2\Exception and access the request and response packets.

```APIDOC
## Example: Catching NetDNS2\Exception

### Description
Demonstrates how to catch NetDNS2\Exception and use getCode(), getMessage(), getResponse(), and getRequest().

### Code
```php
try {
    $res = $r->query('google.com', 'A');
} catch (\NetDNS2\Exception $e) {
    printf("code=%d message=%s\n", $e->getCode(), $e->getMessage());

    if ($e->getResponse() !== null) {
        // server-level failure (rcode, TSIG mismatch, bad header)
        echo "rcode: " . $e->getResponse()->header->rcode->label() . "\n";
    }
    if ($e->getRequest() !== null) {
        // inspect what was sent
        echo $e->getRequest()->header;
    }
} catch (\Throwable $e) {
    // only PHP-level errors otherwise escape
}
```
```

--------------------------------

### Updater TSIG Authentication

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of using the NetDNS2 Updater to sign a request with TSIG.

```php
//
// create a new Updater object
//
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);

//
// add a TSIG to authenticate the request
//
$u->signTSIG('mykey', '9dnf93asdf39fs');

//
// send the update request.
//
$u->update();
```

--------------------------------

### Notifier TSIG Authentication

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of using the NetDNS2 Notifier to authenticate a notification request with TSIG.

```php
//
// create a new Notifier object
//
$n = new \NetDNS2\Notifier('netdns2.com', ['nameservers' => [ '192.168.0.1' ]]);

//
// add a TSIG to authenticate the request
//
$n->signTSIG('mykey', '9dnf93asdf39fs');

//
// trigger a notify request
//
$n->notify();
```

--------------------------------

### NetDNS2\Question::set

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/question.md

Reads the expanded qname (with compression-pointer following and cycle detection), then unpacks qtype/qclass as two 16-bit values, advancing the packet offset by 4.

```APIDOC
## NetDNS2\Question::set

### Description
Reads the expanded qname (with compression-pointer following and cycle detection), then unpacks qtype/qclass as two 16-bit values, advancing $_packet->offset by 4.

### Method
set

### Signature
public function set(\NetDNS2\Packet &$_packet): void

### Parameters
- **$_packet** (\NetDNS2\Packet) - Required - Reference to a Packet object from which to parse the question.

### Throws
- \NetDNS2\Exception - INT_INVALID_PACKET when fewer than 4 bytes remain; INT_PARSE_ERROR when unpack() fails.
```

--------------------------------

### Upgrade Resolver usage from v1.x to v2.x

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Comparison of class instantiation and exception handling between NetDNS2 v1.x and v2.x namespaces.

```php
try  
{
    $r = new Net_DNS2_Resolver([ 'nameservers' => [ '192.168.0.1' ]]);

    $res = $r->query('google.com', 'MX');

} catch(Net_DNS2_Exception $e)
{     
    print_r($e);
}
```

```php
try   
{
    $r = new \NetDNS2\Resolver([ 'nameservers' => [ '192.168.0.1' ]]);

    $res = $r->query('google.com', 'MX');

} catch(\NetDNS2\Exception $e)  
{
    print_r($e);
}
```

--------------------------------

### Constructor: __construct(?array $_options = null)

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/client.md

Initializes a new NetDNS2 Resolver instance. Accepts an optional associative array of options; the 'nameservers' key is passed to setServers(), and other keys are assigned directly to properties.

```APIDOC
## Constructor: __construct(?array $_options = null)

### Description
Initializes a new NetDNS2 Resolver instance. Accepts an optional associative array of options; the 'nameservers' key is passed to setServers(), and other keys are assigned directly to properties.

### Method
Constructor

### Signature
public function __construct(?array $_options = null)

### Parameters
- **$_options** (?array<string,mixed>) - Optional - Associative array of options. The special key 'nameservers' is routed to setServers(); all other keys are assigned directly to properties ($this->$key = $value).

### Throws
- \NetDNS2\Exception - Propagates from Cache::factory() if a non-CACHE_TYPE_NONE cache type is configured and the backend cannot be constructed (e.g. missing shmop/memcached/redis extension).
```

--------------------------------

### Delete all records for a name

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/updater.md

Example showing how to delete all records associated with a specific name using the Updater class.

```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', 'secret');
$u->deleteAll('test.example.com');
$u->update();
```

--------------------------------

### Signing Update Records

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/rr-types.md

Example of using the Updater class to sign a DNS update request with a TSIG key.

```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', '9dnf93asdf39fs', \NetDNS2\RR\TSIG::HMAC_SHA256);
$u->add(\NetDNS2\RR::fromString('test.example.com 600 IN A 2.2.2.2'));
$u->update();
```

--------------------------------

### Question set() Method

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/question.md

Reads the qname and unpacks qtype and qclass from the provided packet, advancing the packet offset.

```php
public function set(\NetDNS2\Packet &$_packet): void
```

--------------------------------

### Configure NetDNS2 Resolver Options

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Demonstrates how to pass an array of configuration options to the NetDNS2\Resolver constructor to customize name servers, timeouts, transport protocols, and caching behavior.

```php
$r = new \NetDNS2\Resolver(
[
	//
	// an array of IP addresses to use as name servers. If this is unset it will 
	// default to using the /etc/resolv.conf file.
	//
	// array, defaults to unset.
	//
	'nameservers'   => [ '1.1.1.1', '8.8.8.8' ],

	//
	// tells NetDNS2 to randomize the name servers list each time it’s used.
	//
	// boolean, defaults to false
	//
	'ns_random'     => true,

	//
	// timeout value to use for socket connections, provided as float, with microsecond 
	// precision. e.g. a value of 1.0 will timeout in 1 second. A value of 0.05 will 
	// timeout in 50 milliseconds.
	//
	// float, defaults to 5 seconds
	//
	'timeout'       => 0.05,

	//
	// tells NetDNS2 to use TCP instead of UDP for queries. UDP is faster, but is limited 
	// in size. NetDNS2 will automatically use TCP for zone transfers (AFXR) and when 
	// a response was truncated.
	//
	// in the event of a truncated response, NetDNS2 will switch to TCP, and resend the 
	// request.
	//
	// boolean, defaults to false.
	//
	'use_tcp'       => true,

	//
	// use DNS over TLS (DoT) this requires OpenSSL support enabled in PHP
	//
	// enabling this option will also enable use_tcp, and sets the default port to 853
	//
	// boolean, defaults to false.
	//
	'use_tls'       => true,

	//
	// if set, these values are passed to stream_context_create() as the 'ssl' transport 
	// section, which lets you customize TLS connection settings.
	//
	// only applies when use_tls = true
	//
	// array, defaults to empty
	//
	'tls_context'   => [ 'verify_peer' => false, 'verify_peer_name' => false ],

	//
	// DNS Port to use; -1 means default of 53 (or 853 when using DoT)
	//
	// int, defaults to -1
	//
	'dns_port'      => 53,

	//
	// the local IP address to bind to when making outbound requests.
	//
	// string, defaults to unset.
	//
	'local_host'    => '',

	//
	// the local port number to bind to when making outbound requests. local_host can be 
	// set without this setting, and the system will auto-allocate the port from the 
	// ephemeral ports.
	//
	// int, defaults to 0 (unset)
	//
	'local_port'    => 0,

	//
	// The default domain to use for unqualified host names.
	//
	// string, defaults to unset
	//
	'domain'        => 'netdns2.com',

	//
	// defines the type of cache to use, using a pre-defined ENUM option. valid options 
	// are:
	//
	//  \NetDNS2\Cache::CACHE_TYPE_NONE         - disables the local cache
	//  \NetDNS2\Cache::CACHE_TYPE_FILE         - flat file cache
	//  \NetDNS2\Cache::CACHE_TYPE_SHM          - shared memory (requires Shmop extension)
	//  \NetDNS2\Cache::CACHE_TYPE_MEMCACHED    - memcache (requires Memcached extension)
	//  \NetDNS2\Cache::CACHE_TYPE_REDIS        - redis (requires Redis extension)
	//
	// int, defaults to \NetDNS2\Cache::CACHE_TYPE_NONE
	//
	'cache_type'    => \NetDNS2\Cache::CACHE_TYPE_MEMCACHED,

	//
	// options to pass to the underlying caching objects
	//
	// array, defaults to empty
	//
	'cache_options' => [ 

		'server' => [

			[ '127.0.0.1', 11211 ]
		],
		'options' => [

			\Memcached::OPT_COMPRESSION => true
		]
	]
]);
```

--------------------------------

### update()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/updater.md

Executes the queued update. Internally calls initNetwork(), checkServers(Client::RESOLV_CONF), appends the auth signature, syncs header counts, requires qdcount > 0 && nscount > 0 (else throws INT_INVALID_PACKET), sends via Client::sendPacket(), then resets the internal packet and the name-compression cache.

```APIDOC
## update()

### Description
Executes the queued update. Internally calls initNetwork(), checkServers(Client::RESOLV_CONF), appends the auth signature, syncs header counts, requires qdcount > 0 && nscount > 0 (else throws INT_INVALID_PACKET), sends via Client::sendPacket(), then resets the internal packet and the name-compression cache.

### Method
public function update(?\NetDNS2\Packet\Response &$_response = null): bool

### Parameters
- **$_response** (?\NetDNS2\Packet\Response &) - Optional - By-reference output; receives the server response

### Returns
bool - always true on success (the response is not needed for updates)

### Throws
\NetDNS2\Exception - INT_INVALID_PACKET for empty question/update sections; transport/RCODE exceptions from sendPacket() (e.g. NOTAUTH, REFUSED, YXDOMAIN, NXRRSET)

### Example - staged update with prerequisites and error handling
```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', '9dnf93asdf39fs');

$u->checkNotExists('test.example.com', 'A');           // prerequisite
$u->add(\NetDNS2\RR::fromString('test.example.com 600 IN A 2.2.2.2'));

try {
    $u->update();
    echo "update OK\n";
} catch (\NetDNS2\Exception $e) {
    printf("update failed (code %d): %s\n", $e->getCode(), $e->getMessage());
    if ($e->getResponse() !== null) {
        echo "server rcode: " . $e->getResponse()->header->rcode->label() . "\n";
    }
}
```

### Example - delete all records for a name
```php
$u = new \NetDNS2\Updater('example.com', [ 'nameservers' => [ '192.168.0.1' ]]);
$u->signTSIG('mykey', 'secret');
$u->deleteAll('test.example.com');
$u->update();
```
```

--------------------------------

### Catching NetDNS2\Exception

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/exception.md

Example of catching the library exception and inspecting the associated request and response packets for diagnostic information.

```php
try {
    $res = $r->query('google.com', 'A');
} catch (\NetDNS2\Exception $e) {
    printf("code=%d message=%s\n", $e->getCode(), $e->getMessage());

    if ($e->getResponse() !== null) {
        // server-level failure (rcode, TSIG mismatch, bad header)
        echo "rcode: " . $e->getResponse()->header->rcode->label() . "\n";
    }
    if ($e->getRequest() !== null) {
        // inspect what was sent
        echo $e->getRequest()->header;
    }
} catch (\Throwable $e) {
    // only PHP-level errors otherwise escape
}
```

--------------------------------

### Parsing a DNS Response

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/packet.md

Example of iterating through answer records and accessing response metadata like source and duration.

```php
$res = new \NetDNS2\Packet\Response($wire_bytes, strlen($wire_bytes));

foreach ($res->answer as $rr) {
    echo $rr->name . ' ' . $rr->ttl . ' ' . $rr->class->label() . ' ' . $rr->type->label() . "\n";
}
echo "from: " . $res->answer_from . " in " . $res->response_time . "s\n";
```

--------------------------------

### Method: update()

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/updater.md

Executes the queued update. It initializes the network, appends signatures, and sends the packet.

```php
public function update(?\NetDNS2\Packet\Response &$_response = null): bool
```

--------------------------------

### Perform a Zone Transfer (AXFR)

Source: https://github.com/mikepultz/netdns2/blob/master/README.md

Example of performing an AXFR zone transfer request, including TSIG authentication.

```php
try
{
	//
	// create new resolver object, passing in an array of name servers to use for lookups
	//
	$r = new \NetDNS2\Resolver([ 'nameservers' => [ '192.168.0.1' ]]);

	//
	// add a TSIG to authenticate the request
	//
	$r->signTSIG('mykey', '9dnf93asdf39fs');

	//
	// execute the zone transfer request for example.com
	//
	$res = $r->query('example.com', 'AXFR');

	//
	// loop through the answer, printing out each resource record.
	//
	foreach($res->answer as $rr)
	{
		print_r($rr);
	}

} catch(\NetDNS2\Exception $e)
{
	echo "::query() failed: ", $e->getMessage(), "\n";
}
```

--------------------------------

### Constructor definition

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/private-key.md

The constructor accepts an optional file path. If provided, it calls parseFile(); otherwise, it initializes an empty container.

```php
public function __construct(?string $_file = null)
```

--------------------------------

### Standard validation flow with error handling

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/dnssec-validator.md

Demonstrates a complete flow for initializing a resolver, setting up the validator with root anchors, and validating a query response.

```php
try {
    $r = new \NetDNS2\Resolver([ 'nameservers' => [ '1.1.1.1' ]]);
    $r->dnssec = true;

    $v = new \NetDNS2\DNSSEC\Validator($r);
    $v->useRootTrustAnchor();

    $res = $r->query('example.com', 'A');
    $v->validate($res);

    echo "signature chain verified successfully\n";

} catch (\NetDNS2\Exception $e) {
    printf("DNSSEC validation failed (code %d): %s\n", $e->getCode(), $e->getMessage());
}
```

--------------------------------

### NetDNS2\Cache\Model\Data Trait

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/cache.md

Shared file/shm storage model providing get, put, clean, and resize methods for cache entries.

```APIDOC
## NetDNS2\Cache\Model\Data Trait

### Description
Shared file/shm storage model. Holds $cache_data (key to array with 'cache_date', 'ttl', 'object') and $cache_opened. Provides methods for retrieving, storing, cleaning, and resizing cache entries.

### Methods
- **get(string $_key): \NetDNS2\Packet\Response|false** - Unserializes the stored object with allowed classes from Cache::allowedCacheClasses(). Returns the Response object or false on failure.
- **put(string $_key, \NetDNS2\Packet\Response $_data): void** - Computes TTL, deep-clones the response (clearing rdata/rdlength on the packet and every RR) to ensure independence, then stores a serialized entry.
- **protected clean(): void** - Removes expired entries and adjusts TTLs.
- **protected resize(): ?string** - Evicts lowest-TTL entries until the serialized store fits m_options['size']. Returns null if the store would be empty.
```

--------------------------------

### Response Constructor and set() Signatures

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/packet.md

The constructor and set() method for parsing binary DNS response data.

```php
public function __construct(string $_data, int $_size)
public function set(string $_data, int $_size): bool
```

--------------------------------

### Initialize NetDNS2 Redis Cache

Source: https://github.com/mikepultz/netdns2/blob/master/_autodocs/api-reference/cache.md

Initializes a Redis cache backend using the factory method. Requires host and port configuration, with additional options passed to the Redis constructor.

```php
$cache = \NetDNS2\Cache::factory(\NetDNS2\Cache::CACHE_TYPE_REDIS, [
    'host' => '127.0.0.1',
    'port' => 6379,
]);
```
Tokens:
Raw