Dns Laravel Package

Getting Started

Install via Composer: composer require react/dns. Start with the Factory to create a resolver using system-configured DNS servers (loaded blocking — do this once at bootstrap). For quick testing, pass a nameserver like '8.8.8.8' directly. The most common first use is resolving a hostname to a single IP with resolve() — returns a promise that resolves with the IP string or rejects with an exception on failure.

$factory = new React\Dns\Resolver\Factory();
$dns = $factory->createCached('8.8.8.8'); // Uses caching by default in `createCached`
$dns->resolve('example.com')->then(fn($ip) => echo "Resolved: $ip\n");

Key first steps:

1. Avoid calling Config::loadSystemConfigBlocking() repeatedly — call it once before the loop starts.
2. Prefer createCached() over create() unless you explicitly need no caching.
3. Use resolve() for simple A lookups; use resolveAll($host, Message::TYPE_* ) when you need multiple records (e.g., AAAA, MX).

Implementation Patterns

• Standard Resolver Pipeline: Wrap executors in stacks (TimeoutExecutor, RetryExecutor, CoopExecutor) for robustness:

$executor = new CoopExecutor(
    new RetryExecutor(
        new TimeoutExecutor(
            new UdpTransportExecutor('8.8.8.8:53'),
            3.0
        )
    )
);
$resolver = new Resolver($executor, $config);

• Caching Strategy: Use ArrayCache for CLI scripts or request-scoped caching. For long-running processes (e.g., workers), consider persistent cache adapters like react/cache-redis to share lookups across processes.
• Hosts File Integration: The default factory includes HostsFileExecutor for /etc/hosts resolution — no extra config needed. Ideal for dev/test environments or overriding production DNS.
• Concurrent Resolution: Leverage promises for parallel lookups — each resolve() call is non-blocking:

$hosts = ['a.com', 'b.com', 'c.com'];
$promises = array_map(fn($h) => $dns->resolve($h), $hosts);
all($promises)->then(fn($ips) => print_r($ips));

• Transport Fallback: Use SelectiveTransportExecutor to automatically fall back to TCP on truncated UDP responses (e.g., for large DNSSEC responses).

Gotchas and Tips

• Blocking in CLI/Long-running apps: Config::loadSystemConfigBlocking() and HostsFileExecutor load files synchronously. Cache their results — don’t call them inside event callbacks.
• UDP reliability: By default, UdpTransportExecutor lacks timeouts and retries — always compose with TimeoutExecutor and RetryExecutor, or use createCached() which does this internally.
• Cancellation matters: Cancel unresolved promises to avoid memory leaks in long-running services. ReactPHP promises support .cancel(), but DNS queries are tied to socket resources — uncancelled promises may hold open sockets.
• Query types matter: resolve() only returns IPv4 (A). Use resolveAll($host, Message::TYPE_AAAA) for IPv6. For SRV/MX, inspect Record objects in the answers array — don’t assume string IPs.
• Cache key collisions: Custom caches should scope by query type and class — the default in-memory cache handles this correctly, but third-party adapters must respect (domain, type, class) uniqueness.
• Testing tip: Use MockExecutor or override config with '127.0.0.1' to avoid network calls in unit tests — write mocks that resolve with new Response(Message::CODE_NOERROR, ...).