DNS

The DNS component provides async DNS resolution with connection pooling, EDNS0, DNS-over-TLS, DNS-over-HTTPS, system configuration detection, hosts file support, and search domain expansion. All resolvers are non-blocking and composable via the decorator pattern.

Basic Usage

SystemResolver mirrors your operating system's DNS behavior. It can be used as a default parameter value since it requires no arguments.

@example('protocols/dns-basic.php')

By default, SystemResolver uses plain UDP with TCP fallback for each nameserver discovered from the OS. You can encrypt all system DNS traffic with DNS-over-TLS by disabling UDP and passing a TLS-enabled connector. With udp: false, all queries go directly over TCP — no plaintext UDP is sent. Combined with a TLS connector, this turns all system nameserver communication into DNS-over-TLS (DoT, RFC 7858) while still using the OS-configured nameserver addresses.

@example('protocols/dns-system-dot.php')

Resolver Types

Resolvers can be composed for different strategies: direct UDP/TCP, fallback on truncation, racing multiple nameservers, DNS-over-TLS, or DNS-over-HTTPS.

@example('protocols/dns-resolvers.php')

Record Types

Over 20 DNS record types are supported. Responses provide typed access via getAnswerRecords() and getFirstAnswerRecord().

@example('protocols/dns-records.php')

Caching

CachedResolver wraps any resolver with TTL-aware caching. Cache TTL is derived from the minimum record TTL in each response.

@example('protocols/dns-caching.php')

Split-Horizon DNS

SplitHorizonResolver routes queries to different resolvers based on the domain name. Domain matching is suffix-based on domain boundaries.

@example('protocols/dns-split-horizon.php')

Search Domains

SearchDomainResolver expands short names by appending search domains. Names with sufficient dots (configurable via $numberOfDots) are queried as-is.

@example('protocols/dns-search-domains.php')

System Configuration

Load your OS DNS settings and hosts file directly. Both use async process execution for non-blocking reads.

@example('protocols/dns-system.php')

EDNS0 Options

Pass EDNS0 options to any query for features like DNS cookies, client subnet hints, padding, and NSID.

@example('protocols/dns-edns.php')

DNS-over-HTTPS

HTTPSResolver sends queries over HTTPS (RFC 8484) using the HTTP client. HTTP/2 multiplexing allows concurrent queries to share a single connection. Pass your own ClientInterface to share connection pools across resolvers.

@example('protocols/dns-doh.php')

Blocking System Resolver

BlockingSystemResolver wraps PHP's built-in dns_get_record() for synchronous DNS resolution with zero overhead. No event loop, no fibers, no connection pooling. Useful as a lightweight fallback behind a StaticResolver, or in environments where async DNS is unnecessary.

Supports A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT, CAA, and NAPTR record types. EDNS0 options are ignored. Queries for unsupported types return NXDOMAIN.

@example('protocols/dns-blocking.php')

HTTP Client Integration

DNS\HTTP\Connector is a connector decorator that resolves hostnames via any DNS resolver before delegating to an inner HTTP client connector. This enables fully async DNS resolution, DNS-over-TLS, DNS-over-HTTPS, DNSSEC validation, or custom resolution strategies for all HTTP requests.

When the origin host is already an IP address, no DNS query is performed. For HTTPS connections, the original hostname is preserved for TLS SNI so certificate validation works correctly even though the TCP connection targets the resolved IP.

@example('protocols/dns-http-connector.php')

Kitchen Sink

Compose static entries, hosts file, search domains, split-horizon routing, multiple racing nameservers with DNS-over-TLS or DNS-over-HTTPS, TCP fallback, and caching into a single resolver that uses every feature.

@example('protocols/dns-kitchen-sink.php')

Supported Record Types

System Configuration Sources

RFC Compliance

See src/Psl/DNS/ for the full API.