Search by

rafalmasiarek / dns-resolver

rafalmasiarek

DNS resolver contract and a from-scratch client (A/AAAA/MX/TXT/PTR, EDNS0, TCP fallback, failover, caching) with a zero-config system-resolver default.

Package info

github.com/rafalmasiarek/php-dns-resolver

pkg:composer/rafalmasiarek/dns-resolver

Statistics

Installs: 72

Dependents: 5

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.1 2026-10-07 14:15 UTC

This package is auto-updated.

Last update: 2026-11-17 23:37:47 UTC


README

DNS resolver contract with two implementations:

  • SystemDnsResolver — zero-config, backed by PHP's own dns_get_record()/gethostbyaddr().
  • DnsClient/FailoverDnsClient — from-scratch raw UDP/TCP client targeting an explicit resolver, with its own timeout, independent of the system resolver.

Features

  • Record types: A, AAAA, MX (preference-sorted), TXT, PTR.
  • EDNS0 (RFC 6891): 4096-byte UDP payload advertisement + DNSSEC OK bit, with automatic TCP fallback when a response still arrives truncated.
  • AD (Authenticated Data) bit reporting on every answer — a soft signal that the queried resolver validated DNSSEC, not a cryptographic guarantee.
  • FailoverDnsClient: ordered multi-resolver failover, PSR-3 audit logging, and an optional total-timeout bounding every attempt across all configured resolvers combined.
  • resolveManyA(): concurrent batch A-record resolution over non-blocking sockets, with duplicate hostnames collapsed before querying.
  • CachingDnsResolver: TTL-respecting decorator for any DnsResolverInterface, backed by the included InMemoryDnsCache or a custom DnsCacheInterface implementation.

License

License: MIT

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files, to deal in the Software
without restriction.

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

Source: https://opensource.org/licenses/MIT

See LICENSE for full details.

Authors

Index

Classes

Interfaces

CachingDnsResolver

final class — rafalmasiarek\DnsResolver\CachingDnsResolver · source

Decorates any DnsResolverInterface with a TTL-respecting cache, keyed per query type + hostname. Entries with a TTL of 0 (unknown/do-not-cache, including every NXDOMAIN without an authority SOA) are never stored. resolveManyA() is intentionally not cached here — it already fans out per hostname in the wrapped resolver, and caching a batch result per-hostname would need to special-case partial hits; cache the individual resolveA() calls instead if that matters for your use case.

implements DnsResolverInterface

Depends on: DnsCacheInterface

Method Visibility Returns Summary
__construct() public — —
resolveA() public DnsAnswer Resolves the A records for a hostname.
resolveAAAA() public DnsAnswer Resolves the AAAA records for a hostname.
resolveMx() public DnsAnswer Resolves the MX records for a domain.
resolveTxt() public DnsAnswer Resolves the TXT records for a hostname.
resolvePtr() public DnsAnswer Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.
resolve() public DnsAnswer Resolves the best available address for a hostname, trying IPv4 and IPv6 in whichever order the implementation is configured to prefer, falling back to the other family when the preferred one yields no records.
resolveManyA() public array<string, DnsAnswer|DnsQueryException> Resolves the A records for several hostnames concurrently instead of one at a time, so the total wait is bounded by the slowest single query rather than the sum of all of them. Duplicate hostnames are queried once.
cached() private DnsAnswer —
__construct()

CachingDnsResolver __construct()

source

public function __construct(DnsResolverInterface $inner, DnsCacheInterface $cache)
Param Type Description
$inner DnsResolverInterface Resolver to cache the results of.
$cache DnsCacheInterface Storage backend; a fresh InMemoryDnsCache when omitted.
resolveA()

CachingDnsResolver resolveA()

source

public function resolveA(string $hostname): DnsAnswer

Resolves the A records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the query cannot be completed.
resolveAAAA()

CachingDnsResolver resolveAAAA()

source

public function resolveAAAA(string $hostname): DnsAnswer

Resolves the AAAA records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the query cannot be completed.
resolveMx()

CachingDnsResolver resolveMx()

source

public function resolveMx(string $hostname): DnsAnswer

Resolves the MX records for a domain.

Param Type Description
$hostname string Fully-qualified domain to query.

Returns: DnsAnswer — Records are mail exchanger hostnames, ordered by ascending preference (lowest/most-preferred first).

Throws When
DnsQueryException When the query cannot be completed.
resolveTxt()

CachingDnsResolver resolveTxt()

source

public function resolveTxt(string $hostname): DnsAnswer

Resolves the TXT records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer — Each record is one TXT record's full text (its character-strings concatenated, per convention).

Throws When
DnsQueryException When the query cannot be completed.
resolvePtr()

CachingDnsResolver resolvePtr()

source

public function resolvePtr(string $ip): DnsAnswer

Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: DnsAnswer — Records are hostnames, not addresses. Empty on NXDOMAIN.

Throws When
\InvalidArgumentException When $ip is not a valid IPv4 or IPv6 address.
DnsQueryException When the query cannot be completed.
resolve()

CachingDnsResolver resolve()

source

public function resolve(string $hostname): DnsAnswer

Resolves the best available address for a hostname, trying IPv4 and IPv6 in whichever order the implementation is configured to prefer, falling back to the other family when the preferred one yields no records.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When neither address family can be resolved.
resolveManyA()

CachingDnsResolver resolveManyA()

source

public function resolveManyA(array $hostnames): array

Resolves the A records for several hostnames concurrently instead of one at a time, so the total wait is bounded by the slowest single query rather than the sum of all of them. Duplicate hostnames are queried once.

Param Type Description
$hostnames list<string> Fully-qualified hostnames to query.

Returns: array<string, DnsAnswer\|DnsQueryException> — Keyed by hostname. Each value is either a successful DnsAnswer or the DnsQueryException/DnsTimeoutException that occurred for that hostname — one host's failure never affects another's result.

cached()

CachingDnsResolver cached()

source

private function cached(string $type, string $key, callable $resolve): DnsAnswer
Param Type Description
$type string —
$key string —
$resolve callable —

Returns: DnsAnswer

DnsAnswer

final readonly class — rafalmasiarek\DnsResolver\DnsAnswer · source

Result of a DNS query, including the TTL to honor for caching.

Method Visibility Returns Summary
__construct() public — —
__construct()

DnsAnswer __construct()

source

public function __construct(array $records, int $ttl, bool $authenticatedData)
Param Type Description
$records list<string> IPv4 or IPv6 addresses from the answer. Empty when the hostname has no record of the queried type.
$ttl int Seconds this answer may be cached for. 0 when unknown — callers should treat that as "do not cache".
$authenticatedData bool Whether the resolver's response carried the DNS header's AD (Authenticated Data) bit, i.e. the resolver itself validated DNSSEC for this answer. Always false for resolvers that cannot observe the raw header (e.g. SystemDnsResolver).

DnsCacheInterface

interface — rafalmasiarek\DnsResolver\DnsCacheInterface · source

Storage backend for CachingDnsResolver. Deliberately not PSR-16 — this package has no dependencies, and this contract is narrow enough (a single value type, TTL-aware) that PSR-16's generic get/set/delete surface would add nothing. Implement to back CachingDnsResolver with Redis, APCu, etc.

Method Visibility Returns Summary
get() public DnsAnswer|null —
set() public void —
get()

DnsCacheInterface get()

source

public function get(string $key): ?DnsAnswer
Param Type Description
$key string —

Returns: DnsAnswer\|null — Null on a cache miss or an expired entry.

set()

DnsCacheInterface set()

source

public function set(string $key, DnsAnswer $answer, int $ttl): void
Param Type Description
$key string —
$answer DnsAnswer —
$ttl int Seconds until the entry expires. Callers never pass 0 or negative values — CachingDnsResolver skips storing those.

DnsClient

final class — rafalmasiarek\DnsResolver\DnsClient · source

From-scratch DNS client (RFC 1035) resolving over raw UDP/TCP against an explicit resolver, with its own connect/read timeout. Does not use the system resolver (dns_get_record()/checkdnsrr() always query whatever is configured in /etc/resolv.conf and have no per-call timeout) — this client always targets the resolver IP given at construction time. Sends EDNS0 (RFC 6891): an OPT pseudo-record advertising a 4096-byte UDP payload size and requesting the DNSSEC OK (DO) bit, so most answers that would otherwise truncate at the classic 512-byte UDP limit (large TXT/SPF records, domains with many MX records) fit in a single UDP response. When a response still arrives with the TC (truncated) bit set, the same query is retried once over TCP. Message encoding/decoding lives in DnsMessageEncoder/DnsMessageDecoder (pure, socket-free); the wire transport lives in Transport\UdpTransport/ TcpTransport. This class owns only the per-type public API, the UDP-then-TCP-on-truncation orchestration, and the concurrent batch path.

implements DnsResolverInterface

Depends on: UdpTransport, TcpTransport

Property Type Visibility Description
$udpTransport UdpTransport private readonly —
$tcpTransport TcpTransport private readonly —
Method Visibility Returns Summary
__construct() public — —
withTimeout() public self Returns a clone of this client with a different timeout — used by FailoverDnsClient to shrink the per-attempt timeout to whatever budget remains under a total-timeout cap, without affecting this instance.
resolveA() public DnsAnswer Resolves the A records for a hostname.
resolveAAAA() public DnsAnswer Resolves the AAAA records for a hostname.
resolveMx() public DnsAnswer Resolves the MX records for a domain.
resolveTxt() public DnsAnswer Resolves the TXT records for a hostname.
resolvePtr() public DnsAnswer Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.
reverseDnsName() private static string Builds the in-addr.arpa (IPv4) or ip6.arpa (IPv6) query name for an address.
resolve() public DnsAnswer Resolves the best available address for a hostname, always trying A first then AAAA — this single resolver has no notion of family preference; that policy lives in FailoverDnsClient, which queries this method's two siblings directly instead of calling this one.
resolveManyA() public array<string, DnsAnswer|DnsQueryException> Resolves the A records for several hostnames concurrently: one UDP socket per hostname (duplicates collapsed first), all queries sent immediately, then a single stream_select() loop collects whichever responses arrive first — so the total wait is bounded by the slowest single query (up to $this->timeout) rather than the sum of every query's own timeout. No TCP-truncation fallback here — A-record responses for the handful of addresses a single query returns do not truncate in practice, and adding a second, sequential TCP round-trip per truncated host would defeat the point of resolving concurrently.
query() private DnsAnswer Sends a single-question query of the given type over UDP, retrying once over TCP if the UDP response comes back truncated, and parses the result.
__construct()

DnsClient __construct()

source

public function __construct(string $resolver, int $port, float $timeout)
Param Type Description
$resolver string Resolver IP address to query.
$port int Resolver port.
$timeout float Socket connect + read timeout, in seconds.
withTimeout()

DnsClient withTimeout()

source

public function withTimeout(float $timeout): self

Returns a clone of this client with a different timeout — used by FailoverDnsClient to shrink the per-attempt timeout to whatever budget remains under a total-timeout cap, without affecting this instance.

Param Type Description
$timeout float —

Returns: self

resolveA()

DnsClient resolveA()

source

public function resolveA(string $hostname): DnsAnswer

Resolves the A records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
resolveAAAA()

DnsClient resolveAAAA()

source

public function resolveAAAA(string $hostname): DnsAnswer

Resolves the AAAA records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
resolveMx()

DnsClient resolveMx()

source

public function resolveMx(string $hostname): DnsAnswer

Resolves the MX records for a domain.

Param Type Description
$hostname string Fully-qualified domain to query.

Returns: DnsAnswer — Records are mail exchanger hostnames, ordered by ascending preference.

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
resolveTxt()

DnsClient resolveTxt()

source

public function resolveTxt(string $hostname): DnsAnswer

Resolves the TXT records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer — Each record is one TXT record's full text.

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
resolvePtr()

DnsClient resolvePtr()

source

public function resolvePtr(string $ip): DnsAnswer

Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: DnsAnswer — Records are hostnames, not addresses. Empty on NXDOMAIN.

Throws When
\InvalidArgumentException When $ip is not a valid IPv4 or IPv6 address.
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
reverseDnsName()

DnsClient reverseDnsName()

source

private static function reverseDnsName(string $ip): string

Builds the in-addr.arpa (IPv4) or ip6.arpa (IPv6) query name for an address.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: string

Throws When
\InvalidArgumentException When $ip is not a valid IPv4 or IPv6 address.
resolve()

DnsClient resolve()

source

public function resolve(string $hostname): DnsAnswer

Resolves the best available address for a hostname, always trying A first then AAAA — this single resolver has no notion of family preference; that policy lives in FailoverDnsClient, which queries this method's two siblings directly instead of calling this one.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.
resolveManyA()

DnsClient resolveManyA()

source

public function resolveManyA(array $hostnames): array

Resolves the A records for several hostnames concurrently: one UDP socket per hostname (duplicates collapsed first), all queries sent immediately, then a single stream_select() loop collects whichever responses arrive first — so the total wait is bounded by the slowest single query (up to $this->timeout) rather than the sum of every query's own timeout. No TCP-truncation fallback here — A-record responses for the handful of addresses a single query returns do not truncate in practice, and adding a second, sequential TCP round-trip per truncated host would defeat the point of resolving concurrently.

Param Type Description
$hostnames list<string> Fully-qualified hostnames to query.

Returns: array<string, DnsAnswer\|DnsQueryException> — Keyed by hostname.

query()

DnsClient query()

source

private function query(string $hostname, int $type): DnsAnswer

Sends a single-question query of the given type over UDP, retrying once over TCP if the UDP response comes back truncated, and parses the result.

Param Type Description
$hostname string Fully-qualified hostname to query.
$type int DNS record type.

Returns: DnsAnswer

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure or a malformed/non-NXDOMAIN error response.

DnsMessageDecoder

final class — rafalmasiarek\DnsResolver\DnsMessageDecoder · source

Parses binary DNS response packets (RFC 1035 §4.1.1-4.1.4) into a DnsAnswer. Pure, side-effect-free — no sockets, so testable without a transport. Every field read from the packet is bounds-checked against the packet's actual remaining length before use. A malformed or truncated packet always throws DnsQueryException rather than being silently treated as partially valid — e.g. an answer record whose declared RDLENGTH would read past the end of the packet, or a TXT character-string whose declared length would do the same, is rejected outright instead of returning truncated data.

Method Visibility Returns Summary
isTruncated() public static bool Whether a raw response packet has the TC (truncated) flag set.
decode() public static DnsAnswer Parses a DNS response packet and extracts records of the queried type and a cache TTL.
decodeCharacterStrings() private static string Decodes a TXT record's RDATA: one or more length-prefixed character-strings, concatenated into a single string per the common resolver convention.
findSoaTtl() private static int Scans the authority section for an SOA record and returns its TTL.
decodeName() public static string Decodes a (possibly compressed) domain name starting at $offset, advancing it past the name.
isTruncated()

DnsMessageDecoder isTruncated()

source

public static function isTruncated(string $data): bool

Whether a raw response packet has the TC (truncated) flag set.

Param Type Description
$data string —

Returns: bool

decode()

DnsMessageDecoder decode()

source

public static function decode(string $data, int $expectedId, int $type): DnsAnswer

Parses a DNS response packet and extracts records of the queried type and a cache TTL.

Param Type Description
$data string Raw response packet.
$expectedId int Query id the response must echo back.
$type int DNS record type queried; only answer records of this type are collected.

Returns: DnsAnswer

Throws When
DnsQueryException On a truncated/malformed packet, id mismatch, or an error RCODE other than NXDOMAIN (3).
decodeCharacterStrings()

DnsMessageDecoder decodeCharacterStrings()

source

private static function decodeCharacterStrings(string $rdata): string

Decodes a TXT record's RDATA: one or more length-prefixed character-strings, concatenated into a single string per the common resolver convention.

Param Type Description
$rdata string —

Returns: string

Throws When
DnsQueryException When a character-string's declared length extends past the end of $rdata — a malformed record is rejected outright rather than silently returning truncated text.
findSoaTtl()

DnsMessageDecoder findSoaTtl()

source

private static function findSoaTtl(string $data, int $offset, int $nscount): int

Scans the authority section for an SOA record and returns its TTL.

Param Type Description
$data string Raw response packet.
$offset int Byte offset of the authority section (past the question section).
$nscount int Number of authority records to scan.

Returns: int — The SOA record's TTL, or 0 when no SOA record is present.

Throws When
DnsQueryException On a malformed authority record header or RDATA extending past the end of the packet.
decodeName()

DnsMessageDecoder decodeName()

source

public static function decodeName(string $data, int $offset): string

Decodes a (possibly compressed) domain name starting at $offset, advancing it past the name.

Param Type Description
$data string —
$offset int Byte offset to start reading at; advanced past the encoded name.

Returns: string — Decoded, dot-separated domain name.

Throws When
DnsQueryException On a truncated name, a compression pointer loop, or a decoded name exceeding 255 bytes (RFC 1035 §3.1) — the pointer-loop guard alone bounds the number of jumps to the packet size, but not the total assembled name length.

DnsMessageEncoder

final class — rafalmasiarek\DnsResolver\DnsMessageEncoder · source

Builds binary DNS query packets (RFC 1035 §4.1.1-4.1.3, EDNS0 RFC 6891). Pure, side-effect-free — no sockets, so testable without a transport.

Method Visibility Returns Summary
buildQuery() public static string Builds a single-question DNS query packet with an EDNS0 OPT pseudo-record advertising a 4096-byte UDP payload size and requesting the DNSSEC OK bit.
encodeName() public static string Encodes a hostname as a sequence of length-prefixed labels terminated by a zero byte.
buildOptRecord() private static string Builds the EDNS0 OPT pseudo-record (RFC 6891): root name, TYPE=OPT, CLASS=advertised UDP payload size, TTL carries ext-RCODE(0)+version(0)+ flags (DO bit set, requesting DNSSEC OK), empty RDATA.
buildQuery()

DnsMessageEncoder buildQuery()

source

public static function buildQuery(string $hostname, int $id, int $type): string

Builds a single-question DNS query packet with an EDNS0 OPT pseudo-record advertising a 4096-byte UDP payload size and requesting the DNSSEC OK bit.

Param Type Description
$hostname string —
$id int 16-bit query identifier, echoed back in the response.
$type int DNS record type.

Returns: string — Binary DNS query packet.

Throws When
DnsQueryException When $hostname cannot be encoded (see encodeName()).
encodeName()

DnsMessageEncoder encodeName()

source

public static function encodeName(string $hostname): string

Encodes a hostname as a sequence of length-prefixed labels terminated by a zero byte.

Param Type Description
$hostname string —

Returns: string

Throws When
DnsQueryException When a label is empty (e.g. an embedded ".." inside a non-root hostname — silently encoding it would emit a premature terminator byte and truncate the name on the wire), a label exceeds 63 bytes, or the total encoded name exceeds 255 bytes.
buildOptRecord()

DnsMessageEncoder buildOptRecord()

source

private static function buildOptRecord(): string

Builds the EDNS0 OPT pseudo-record (RFC 6891): root name, TYPE=OPT, CLASS=advertised UDP payload size, TTL carries ext-RCODE(0)+version(0)+ flags (DO bit set, requesting DNSSEC OK), empty RDATA.

Returns: string

DnsQueryException

class — rafalmasiarek\DnsResolver\DnsQueryException · source

Thrown when a DNS query cannot be completed.

extends \RuntimeException

DnsResolverInterface

interface — rafalmasiarek\DnsResolver\DnsResolverInterface · source

Resolves DNS records for a hostname.

Method Visibility Returns Summary
resolveA() public DnsAnswer Resolves the A records for a hostname.
resolveAAAA() public DnsAnswer Resolves the AAAA records for a hostname.
resolveMx() public DnsAnswer Resolves the MX records for a domain.
resolveTxt() public DnsAnswer Resolves the TXT records for a hostname.
resolvePtr() public DnsAnswer Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.
resolve() public DnsAnswer Resolves the best available address for a hostname, trying IPv4 and IPv6 in whichever order the implementation is configured to prefer, falling back to the other family when the preferred one yields no records.
resolveManyA() public array<string, DnsAnswer|DnsQueryException> Resolves the A records for several hostnames concurrently instead of one at a time, so the total wait is bounded by the slowest single query rather than the sum of all of them. Duplicate hostnames are queried once.
resolveA()

DnsResolverInterface resolveA()

source

public function resolveA(string $hostname): DnsAnswer

Resolves the A records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the query cannot be completed.
resolveAAAA()

DnsResolverInterface resolveAAAA()

source

public function resolveAAAA(string $hostname): DnsAnswer

Resolves the AAAA records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the query cannot be completed.
resolveMx()

DnsResolverInterface resolveMx()

source

public function resolveMx(string $hostname): DnsAnswer

Resolves the MX records for a domain.

Param Type Description
$hostname string Fully-qualified domain to query.

Returns: DnsAnswer — Records are mail exchanger hostnames, ordered by ascending preference (lowest/most-preferred first).

Throws When
DnsQueryException When the query cannot be completed.
resolveTxt()

DnsResolverInterface resolveTxt()

source

public function resolveTxt(string $hostname): DnsAnswer

Resolves the TXT records for a hostname.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer — Each record is one TXT record's full text (its character-strings concatenated, per convention).

Throws When
DnsQueryException When the query cannot be completed.
resolvePtr()

DnsResolverInterface resolvePtr()

source

public function resolvePtr(string $ip): DnsAnswer

Resolves the PTR (reverse DNS) record for an IPv4 or IPv6 address.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: DnsAnswer — Records are hostnames, not addresses. Empty on NXDOMAIN.

Throws When
\InvalidArgumentException When $ip is not a valid IPv4 or IPv6 address.
DnsQueryException When the query cannot be completed.
resolve()

DnsResolverInterface resolve()

source

public function resolve(string $hostname): DnsAnswer

Resolves the best available address for a hostname, trying IPv4 and IPv6 in whichever order the implementation is configured to prefer, falling back to the other family when the preferred one yields no records.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When neither address family can be resolved.
resolveManyA()

DnsResolverInterface resolveManyA()

source

public function resolveManyA(array $hostnames): array

Resolves the A records for several hostnames concurrently instead of one at a time, so the total wait is bounded by the slowest single query rather than the sum of all of them. Duplicate hostnames are queried once.

Param Type Description
$hostnames list<string> Fully-qualified hostnames to query.

Returns: array<string, DnsAnswer\|DnsQueryException> — Keyed by hostname. Each value is either a successful DnsAnswer or the DnsQueryException/DnsTimeoutException that occurred for that hostname — one host's failure never affects another's result.

DnsTimeoutException

class — rafalmasiarek\DnsResolver\DnsTimeoutException · source

Thrown when no response arrives within the configured timeout. A subtype of DnsQueryException, so existing catch (DnsQueryException) call sites keep working without changes.

extends DnsQueryException

FailoverDnsClient

final class — rafalmasiarek\DnsResolver\FailoverDnsClient · source

Queries a list of resolvers in order, falling over to the next one when a query fails (timeout or socket error). All resolvers are treated as equal peers — there is no primary/secondary distinction, just an ordered attempt list. Existing NXDOMAIN/success responses are never retried against another resolver, only failed queries. $totalTimeout, when set, bounds the sum of every resolver attempt for a single call: each attempt's own timeout is shrunk to whatever budget remains (via DnsClient::withTimeout()), so the call as a whole cannot run longer than $totalTimeout even across multiple resolver attempts. Only applies to the single-hostname methods below (A/AAAA/MX/TXT/PTR/resolve); resolveManyA() runs its own parallel batch per resolver and is unaffected.

implements DnsResolverInterface

Depends on: LoggerInterface

Property Type Visibility Description
$resolverLabels list<string> private readonly Resolver IP addresses, in attempt order — kept alongside for logging.
$clients list<DnsClient> private readonly One DnsClient per configured resolver, in attempt order.
$logger LoggerInterface private readonly Logger for per-attempt failures and, when audit is true, every attempt.
Method Visibility Returns Summary
__construct() public — —
resolveA() public DnsAnswer Resolves the A records for a hostname, trying each configured resolver in order.
resolveAAAA() public DnsAnswer Resolves the AAAA records for a hostname, trying each configured resolver in order.
resolveMx() public DnsAnswer Resolves the MX records for a domain, trying each configured resolver in order.
resolveTxt() public DnsAnswer Resolves the TXT records for a hostname, trying each configured resolver in order.
resolvePtr() public DnsAnswer Resolves the PTR record for an IP address, trying each configured resolver in order.
resolve() public DnsAnswer Resolves the best available address for a hostname: tries the preferred address family across all configured resolvers first, and only falls back to the other family when the preferred one yields no records.
resolveManyA() public array<string, DnsAnswer|DnsQueryException> Resolves the A records for several hostnames concurrently per resolver: each configured resolver gets one parallel batch attempt (see DnsClient::resolveManyA()) for whatever hostnames are still unresolved, so failover across resolvers only kicks in for the hostnames that actually failed, not for ones that already succeeded.
attempt() private DnsAnswer Runs $call against each configured resolver in order, logging failures (always) and successes (only in audit mode), until one succeeds or the total-timeout budget (when configured) is exhausted.
__construct()

FailoverDnsClient __construct()

source

public function __construct(array $resolvers, int $port, float $timeout, bool $preferIpv6, ?LoggerInterface $logger, bool $audit, ?float $totalTimeout)
Param Type Description
$resolvers list<string> Resolver IP addresses, in attempt order.
$port int Resolver port, shared by all resolvers.
$timeout float Per-attempt timeout, in seconds.
$preferIpv6 bool When true, resolve() tries AAAA before A; otherwise A before AAAA.
$logger LoggerInterface|null Receives failure warnings/errors always, and (when $audit is true) a debug entry for every successful attempt. Defaults to a no-op logger when omitted.
$audit bool When true, logs a debug entry for every successful attempt (host, record type, resolver used, duration, result). Failures are always logged regardless of this flag.
$totalTimeout float|null Bounds the sum of every resolver attempt for a single call, in seconds. Null (default) disables the budget — each resolver always gets its full $timeout.
Throws When
\InvalidArgumentException When $resolvers is empty.
resolveA()

FailoverDnsClient resolveA()

source

public function resolveA(string $hostname): DnsAnswer

Resolves the A records for a hostname, trying each configured resolver in order.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When every configured resolver fails.
resolveAAAA()

FailoverDnsClient resolveAAAA()

source

public function resolveAAAA(string $hostname): DnsAnswer

Resolves the AAAA records for a hostname, trying each configured resolver in order.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When every configured resolver fails.
resolveMx()

FailoverDnsClient resolveMx()

source

public function resolveMx(string $hostname): DnsAnswer

Resolves the MX records for a domain, trying each configured resolver in order.

Param Type Description
$hostname string Fully-qualified domain to query.

Returns: DnsAnswer — Records are mail exchanger hostnames, ordered by ascending preference.

Throws When
DnsQueryException When every configured resolver fails.
resolveTxt()

FailoverDnsClient resolveTxt()

source

public function resolveTxt(string $hostname): DnsAnswer

Resolves the TXT records for a hostname, trying each configured resolver in order.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When every configured resolver fails.
resolvePtr()

FailoverDnsClient resolvePtr()

source

public function resolvePtr(string $ip): DnsAnswer

Resolves the PTR record for an IP address, trying each configured resolver in order.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: DnsAnswer — Records are hostnames, not addresses. Empty on NXDOMAIN.

Throws When
DnsQueryException When every configured resolver fails.
resolve()

FailoverDnsClient resolve()

source

public function resolve(string $hostname): DnsAnswer

Resolves the best available address for a hostname: tries the preferred address family across all configured resolvers first, and only falls back to the other family when the preferred one yields no records.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When neither address family can be resolved by any resolver.
resolveManyA()

FailoverDnsClient resolveManyA()

source

public function resolveManyA(array $hostnames): array

Resolves the A records for several hostnames concurrently per resolver: each configured resolver gets one parallel batch attempt (see DnsClient::resolveManyA()) for whatever hostnames are still unresolved, so failover across resolvers only kicks in for the hostnames that actually failed, not for ones that already succeeded.

Param Type Description
$hostnames list<string> Fully-qualified hostnames to query.

Returns: array<string, DnsAnswer\|DnsQueryException> — Keyed by hostname.

attempt()

FailoverDnsClient attempt()

source

private function attempt(string $type, string $hostname, callable $call): DnsAnswer

Runs $call against each configured resolver in order, logging failures (always) and successes (only in audit mode), until one succeeds or the total-timeout budget (when configured) is exhausted.

Param Type Description
$type string 'A', 'AAAA', 'MX', 'TXT', or 'PTR' — for log context only.
$hostname string Fully-qualified hostname to query.
$call callable —

Returns: DnsAnswer

Throws When
DnsQueryException When every configured resolver fails, or the total-timeout budget is exhausted before any resolver is tried.

InMemoryDnsCache

final class — rafalmasiarek\DnsResolver\InMemoryDnsCache · source

Process-lifetime DnsCacheInterface backed by a plain array. The default CachingDnsResolver store; stateless across requests in a classic PHP-FPM process-per-request model — a long-running worker or CLI process is where this actually saves repeat queries.

implements DnsCacheInterface

Property Type Visibility Description
$entries array<string, array{0: DnsAnswer, 1: float}> private Keyed by cache key; value is [answer, expiresAt].
Method Visibility Returns Summary
get() public DnsAnswer|null —
set() public void —
get()

InMemoryDnsCache get()

source

public function get(string $key): ?DnsAnswer
Param Type Description
$key string —

Returns: DnsAnswer\|null — Null on a cache miss or an expired entry.

set()

InMemoryDnsCache set()

source

public function set(string $key, DnsAnswer $answer, int $ttl): void
Param Type Description
$key string —
$answer DnsAnswer —
$ttl int Seconds until the entry expires. Callers never pass 0 or negative values — CachingDnsResolver skips storing those.

SystemDnsResolver

final class — rafalmasiarek\DnsResolver\SystemDnsResolver · source

Resolves A/AAAA/MX/TXT/PTR records via PHP's own system resolver (dns_get_record(), gethostbyaddr() for PTR). Pins nothing: no explicit nameserver, no custom timeout — whatever the host's resolv.conf and PHP's default DNS timeout behavior already do. This is the baseline DnsResolverInterface implementation; an app that needs an explicit nameserver, a bounded timeout, or failover should provide its own. dns_get_record() has no access to the raw response header, so DnsAnswer::$authenticatedData is always false here — this resolver cannot observe whether the system resolver validated DNSSEC.

implements DnsResolverInterface

Method Visibility Returns Summary
__construct() public — —
resolveA() public DnsAnswer Resolves the A records for a hostname via the system resolver.
resolveAAAA() public DnsAnswer Resolves the AAAA records for a hostname via the system resolver.
resolveMx() public DnsAnswer Resolves the MX records for a domain via the system resolver.
resolveTxt() public DnsAnswer Resolves the TXT records for a hostname via the system resolver.
resolvePtr() public DnsAnswer Resolves the PTR (reverse DNS) record for an IP address via the system resolver.
resolveManyA() public array<string, DnsAnswer|DnsQueryException> Resolves the A records for several hostnames, one at a time via the system resolver — dns_get_record() has no concurrent-query mode, unlike DnsClient's raw-socket resolveManyA(). Provided so SystemDnsResolver stays a drop-in DnsResolverInterface implementation; prefer DnsClient/FailoverDnsClient when resolveManyA()'s concurrency is actually needed.
resolve() public DnsAnswer —
query() private DnsAnswer —
__construct()

SystemDnsResolver __construct()

source

public function __construct(bool $preferIpv6)
Param Type Description
$preferIpv6 bool When true, resolve() tries AAAA before A; otherwise A before AAAA.
resolveA()

SystemDnsResolver resolveA()

source

public function resolveA(string $hostname): DnsAnswer

Resolves the A records for a hostname via the system resolver.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the system resolver reports a lookup failure.
resolveAAAA()

SystemDnsResolver resolveAAAA()

source

public function resolveAAAA(string $hostname): DnsAnswer

Resolves the AAAA records for a hostname via the system resolver.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When the system resolver reports a lookup failure.
resolveMx()

SystemDnsResolver resolveMx()

source

public function resolveMx(string $hostname): DnsAnswer

Resolves the MX records for a domain via the system resolver.

Param Type Description
$hostname string Fully-qualified domain to query.

Returns: DnsAnswer — Records are mail exchanger hostnames, ordered by ascending preference.

Throws When
DnsQueryException When the system resolver reports a lookup failure.
resolveTxt()

SystemDnsResolver resolveTxt()

source

public function resolveTxt(string $hostname): DnsAnswer

Resolves the TXT records for a hostname via the system resolver.

Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer — Each record is one TXT record's full text.

Throws When
DnsQueryException When the system resolver reports a lookup failure.
resolvePtr()

SystemDnsResolver resolvePtr()

source

public function resolvePtr(string $ip): DnsAnswer

Resolves the PTR (reverse DNS) record for an IP address via the system resolver.

Param Type Description
$ip string IPv4 or IPv6 address.

Returns: DnsAnswer — Records are hostnames, not addresses.

Throws When
\InvalidArgumentException When $ip is not a valid IPv4 or IPv6 address.
DnsQueryException When the system resolver reports a lookup failure.
resolveManyA()

SystemDnsResolver resolveManyA()

source

public function resolveManyA(array $hostnames): array

Resolves the A records for several hostnames, one at a time via the system resolver — dns_get_record() has no concurrent-query mode, unlike DnsClient's raw-socket resolveManyA(). Provided so SystemDnsResolver stays a drop-in DnsResolverInterface implementation; prefer DnsClient/FailoverDnsClient when resolveManyA()'s concurrency is actually needed.

Param Type Description
$hostnames list<string> Fully-qualified hostnames to query.

Returns: array<string, DnsAnswer\|DnsQueryException> — Keyed by hostname.

resolve()

SystemDnsResolver resolve()

source

public function resolve(string $hostname): DnsAnswer
Param Type Description
$hostname string Fully-qualified hostname to query.

Returns: DnsAnswer

Throws When
DnsQueryException When both address families fail to resolve.
query()

SystemDnsResolver query()

source

private function query(string $hostname, int $type, string $label): DnsAnswer
Param Type Description
$hostname string Fully-qualified hostname to query.
$type int DNS_A or DNS_AAAA.
$label string 'A' or 'AAAA', matching dns_get_record()'s record 'type' field.

Returns: DnsAnswer

Throws When
DnsQueryException When the system resolver reports a lookup failure.

DnsTransportInterface

interface — rafalmasiarek\DnsResolver\Transport\DnsTransportInterface · source

Sends one already-encoded DNS query packet to a fixed resolver and returns the raw response. Implementations own a single resolver/port/timeout for their whole lifetime — constructed once per DnsClient (or per attempt, via withTimeout()), not parameterized per call.

Method Visibility Returns Summary
send() public string —
send()

DnsTransportInterface send()

source

public function send(string $query): string
Param Type Description
$query string Binary DNS query packet.

Returns: string — Raw response packet.

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure.

TcpTransport

final class — rafalmasiarek\DnsResolver\Transport\TcpTransport · source

Sends a DNS query over TCP (2-byte length prefix framing, RFC 1035 §4.2.2), used as a fallback when a UDP response comes back truncated.

implements DnsTransportInterface

Method Visibility Returns Summary
__construct() public — —
send() public string —
writeFully() private void Writes the entire buffer, looping over partial writes — fwrite() on a TCP stream may accept fewer bytes than given (e.g. a full kernel send buffer), and silently sending only part of the length-prefixed frame would desync the stream for whatever is read next.
readExactly() private string Reads exactly $length bytes from a TCP stream, looping over partial reads.
__construct()

TcpTransport __construct()

source

public function __construct(string $resolver, int $port, float $timeout)
Param Type Description
$resolver string Resolver IP address to query.
$port int Resolver port.
$timeout float Socket connect + read timeout, in seconds.
send()

TcpTransport send()

source

public function send(string $query): string
Param Type Description
$query string Binary DNS query packet.

Returns: string — Raw response packet.

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure.
writeFully()

TcpTransport writeFully()

source

private function writeFully( $socket, string $buffer): void

Writes the entire buffer, looping over partial writes — fwrite() on a TCP stream may accept fewer bytes than given (e.g. a full kernel send buffer), and silently sending only part of the length-prefixed frame would desync the stream for whatever is read next.

Param Type Description
$socket resource —
$buffer string —
Throws When
DnsQueryException When the socket rejects or fails a write.
readExactly()

TcpTransport readExactly()

source

private function readExactly( $socket, int $length): string

Reads exactly $length bytes from a TCP stream, looping over partial reads.

Param Type Description
$socket resource —
$length int —

Returns: string

Throws When
DnsQueryException When the connection closes before $length bytes arrive.

UdpTransport

final class — rafalmasiarek\DnsResolver\Transport\UdpTransport · source

Sends a DNS query over UDP and reads a single response datagram. A single fwrite() of a query this small (well under any realistic path MTU) does not partially write in practice, unlike the TCP transport's stream — see TcpTransport for why that one loops.

implements DnsTransportInterface

Method Visibility Returns Summary
__construct() public — —
send() public string —
__construct()

UdpTransport __construct()

source

public function __construct(string $resolver, int $port, float $timeout)
Param Type Description
$resolver string Resolver IP address to query.
$port int Resolver port.
$timeout float Socket connect + read timeout, in seconds.
send()

UdpTransport send()

source

public function send(string $query): string
Param Type Description
$query string Binary DNS query packet.

Returns: string — Raw response packet.

Throws When
DnsTimeoutException When no response arrives within the timeout.
DnsQueryException On socket failure.