rafalmasiarek / dns-resolver
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.
Requires
- php: >=8.2
- psr/log: ^3.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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 owndns_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 anyDnsResolverInterface, backed by the includedInMemoryDnsCacheor a customDnsCacheInterfaceimplementation.
License
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
CachingDnsResolver—rafalmasiarek\DnsResolverDnsAnswer—rafalmasiarek\DnsResolverDnsClient—rafalmasiarek\DnsResolverDnsMessageDecoder—rafalmasiarek\DnsResolverDnsMessageEncoder—rafalmasiarek\DnsResolverDnsQueryException—rafalmasiarek\DnsResolverDnsTimeoutException—rafalmasiarek\DnsResolverFailoverDnsClient—rafalmasiarek\DnsResolverInMemoryDnsCache—rafalmasiarek\DnsResolverSystemDnsResolver—rafalmasiarek\DnsResolverTcpTransport—rafalmasiarek\DnsResolver\TransportUdpTransport—rafalmasiarek\DnsResolver\Transport
Interfaces
DnsCacheInterface—rafalmasiarek\DnsResolverDnsResolverInterface—rafalmasiarek\DnsResolverDnsTransportInterface—rafalmasiarek\DnsResolver\Transport
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
public function __construct(bool $preferIpv6)
| Param | Type | Description |
|---|---|---|
$preferIpv6 |
bool |
When true, resolve() tries AAAA before A; otherwise A before AAAA. |
resolveA()
SystemDnsResolver resolveA()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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()
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. |