README

A recursive DNS resolver for PHP with full DNSSEC validation. Performs iterative resolution from the root servers down, just like a real resolver — no reliance on the system stub resolver.

The intention of this package is to be a full non-caching resolver implementation. This allows stable and consistent results. It is not designed for latency critical applications or high query volumes. For those use cases, consider using a (local) caching resolver instead.

If you want to see the resolver in action, check out dns.chief.tools — a free online DNS lookup tool built with this package.

Requirements

• PHP 8.4+
• ext-openssl

Installation

composer require chieftools/dns-resolver

Quick start

use ChiefTools\DNS\Resolver\Resolver;
use ChiefTools\DNS\Resolver\Enums\LookupStatus;

$result = new Resolver()->resolve('example.com', 'A');

if ($result->status === LookupStatus::SUCCESS) {
    foreach ($result->records as $record) {
        echo "{$record->name} {$record->ttl} {$record->type->value} {$record->data}\n";
    }
}

Interpreting results

LookupResult::status is the machine-readable outcome of the lookup. info is only a human-readable message for non-success cases.

use ChiefTools\DNS\Resolver\Resolver;
use ChiefTools\DNS\Resolver\Enums\LookupStatus;

$result = new Resolver()->resolve('example.com', 'A');

if ($result->status === LookupStatus::NXDOMAIN) {
    echo "The domain does not exist.\n";
} elseif ($result->status === LookupStatus::QUERY_FAILED) {
    echo "The lookup failed and may succeed on retry.\n";
} elseif ($result->status === LookupStatus::NO_RECORDS) {
    echo "The domain exists, but no records were found for that type.\n";
}

if ($result->isNxdomain()) {
    // Convenience helper for NXDOMAIN checks
}

if ($result->isLookupFailed()) {
    // Convenience helper for transport / nameserver failure checks
}

foreach ($result->records as $record) {
    echo $record->validation->name . "\n"; // SIGNED, FAILED, or UNKNOWN
}

Querying multiple types

Pass an array of types to resolve them in a single call. The resolver queries the authoritative server for each type once it reaches it, avoiding redundant delegation walks.

use ChiefTools\DNS\Resolver\Resolver;

$result = new Resolver()->resolve('example.com', ['A', 'AAAA', 'MX']);

$aRecords = $result->ofType('A');
$mxRecords = $result->ofType(\ChiefTools\DNS\Resolver\Enums\RecordType::MX);

DNSSEC validation

DNSSEC is enabled by default (DnssecMode::ON). The resolver validates the full chain of trust from the root zone trust anchor through every delegation.

use ChiefTools\DNS\Resolver\Resolver;
use ChiefTools\DNS\Resolver\Enums\DnssecMode;

// Validate and report — always returns results (default)
$result = new Resolver()->resolve('example.com', 'A', dnssec: DnssecMode::ON);

echo $result->dnssec->status->value; // "signed", "unsigned", "invalid", or "indeterminate"

// Per-record validation status
foreach ($result->records as $record) {
    echo $record->validation->name; // SIGNED, FAILED, or UNKNOWN
}

// Strict mode — clears records when validation fails
$result = new Resolver()->resolve('example.com', 'A', dnssec: DnssecMode::STRICT);

// Disable DNSSEC entirely
$result = new Resolver()->resolve('example.com', 'A', dnssec: DnssecMode::OFF);

Configuration

use ChiefTools\DNS\Resolver\ResolverConfig;

$resolver = new Resolver(
    config: new ResolverConfig(
        ipv6: false,     // Disable IPv6 for nameserver resolution (default: true)
        timeout: 5,      // Per-query timeout in seconds (default: 2)
        maxDepth: 15,    // Maximum recursive lookups (default: 10)
    ),
);

Custom executor

The resolver ships with NetDns2QueryExecutor (default) and DigQueryExecutor. You can provide your own by implementing the DnsQueryExecutor interface.

DigQueryExecutor requires external dig and jc binaries. If you do not need that integration, the default NetDns2QueryExecutor is the simpler and faster choice.

use ChiefTools\DNS\Resolver\Executors\DigQueryExecutor;

$resolver = new Resolver(
    executor: new DigQueryExecutor(
        digPath: '/usr/local/bin/dig',
        jcPath: '/usr/local/bin/jc',
    ),
);

Event callback

The onEvent callback fires synchronously during resolution, giving real-time visibility into every step. This is useful for streaming UIs, CLI progress output, or debug logging.

use ChiefTools\DNS\Resolver\Resolver;
use ChiefTools\DNS\Resolver\Events\ResolverEvent;

$result = new Resolver()->resolve('example.com', 'A',
    onEvent: function (ResolverEvent $event) {
        // Pre-formatted message for simple output
        echo $event->message . "\n";

        // Or use structured data
        // $event->type      — EventType enum (LOOKUP, QUERY, DELEGATION, CNAME, QUERY_FAILURE, NAMESERVER_FALLBACK, RESOLVE_NAMESERVER, RESOLVE_FAILURE)
        // $event->depth     — nesting level for visual indentation
        // $event->domain    — domain being queried
        // $event->nameserver, $event->address, $event->timeMs, etc.
        // $event->status    — per-step status such as "signed", "unsigned", "invalid", or null on non-query events
    },
);

Result objects

LookupResult

Methods: isEmpty(), isNxdomain(), isLookupFailed(), ofType(RecordType|string)

Record

DnssecResult

Methods: isSigned(), isInvalid()

Supported record types

A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, CAA, DS, DNSKEY, CDS, CDNSKEY, CSYNC, HTTPS, SVCB, DNAME, NAPTR, TLSA, SSHFP, SMIMEA, OPENPGPKEY, CERT, URI, LOC, SPF

Security Vulnerabilities

If you discover a security vulnerability within this project, please report it privately via GitHub: https://github.com/chieftools/dns-resolver/security/advisories/new. All security vulnerabilities will be swiftly addressed. There is no bug bounty program at this time.

License

This package is open-source software licensed under the Apache License 2.0. This means you are free to use, modify, and distribute the software for both commercial and non-commercial purposes. See the LICENSE file for details.