README

A powerful DNS service and facade for Laravel. V4 brings a robust model-based architecture, semantic query methods, and built-in caching.

Installation

Install the package via composer:

composer require jinomial/laravel-dns

Publish the config file:

php artisan vendor:publish --provider="Jinomial\LaravelDns\DnsServiceProvider" --tag="laravel-dns-config"

The default configuration uses Cloudflare DoH:

'doh' => [
    'driver' => 'doh',
    'endpoint' => env('DOH_ENDPOINT', 'https://cloudflare-dns.com/dns-query'),
    'timeout' => 5.0,
],

Usage

V4 returns DnsRecordCollection containing DnsRecord objects, providing a consistent API across drivers.

Basic Query

use Jinomial\LaravelDns\Facades\Dns;

$records = Dns::query('google.com', 'A');

foreach ($records as $record) {
    echo $record->host; // "google.com"
    echo $record->data; // "142.250.xxx.xxx"
    echo $record->ttl;  // 300
}

Semantic Methods

V4 includes convenient semantic methods for common record types:

$a    = Dns::getA('google.com');
$aaaa = Dns::getAAAA('google.com');
$mx   = Dns::getMX('google.com');
$txt  = Dns::getTXT('google.com');
$ns   = Dns::getNS('google.com');
$ptr  = Dns::getPTR('8.8.8.8');

Caching

Easily cache DNS results using the remember method:

// Cache the result for 60 seconds
$records = Dns::remember(60)->getA('google.com');

Use a Specific Driver

$records = Dns::socket('system')->query('google.com', 'A');

Batch Queries

Multiple lookups can be performed at once. In DoH, these can be performed asynchronously.

$records = Dns::query([
    ['name' => 'google.com', 'type' => 'A'],
    ['name' => 'github.com', 'type' => 'AAAA'],
]);

Asynchronous Queries (DoH only)

// Returns a DnsRecordCollection after resolving all promises
$records = Dns::socket('doh')->query($queries, null, ['async' => true]);

DnsRecord Model

The DnsRecord model standardizes DNS data across all drivers:

$record->host;   // The host name
$record->type;   // The record type (e.g., "A", "MX")
$record->ttl;    // Time to live
$record->data;   // The record value (IP, Target, etc.)
$record->class;  // Usually "IN"
$record->extras; // Array of driver-specific raw data

The DnsRecordCollection extends Illuminate\Support\Collection, giving you access to all Laravel collection methods like filter, map, and pluck.

Migration from V3 to V4

V4 is a major refactor focused on type safety and developer experience.

Return Type Changes

• V3: query() returned raw arrays specific to each driver.
• V4: query() returns a Jinomial\LaravelDns\DnsRecordCollection.

Update Needed: If you were accessing array keys directly, update to object properties or use toArray().

// V3
$ip = $response['Answer'][0]['data'];

// V4
$ip = $records->first()->data;

Driver Interface

If you implemented custom drivers, you must update your query() method signature to return DnsRecordCollection.

Manager Changes

DnsManager now extends Illuminate\Support\Manager. forgetDrivers() is still supported but forgetSockets() is preferred for semantic consistency.

Custom Drivers

Create a class that implements Jinomial\LaravelDns\Contracts\Dns\Socket.

Register your driver in a Service Provider:

public function boot(): void
{
    $this->app->make(\Jinomial\LaravelDns\DnsManager::class)->extend('custom', function ($app, $name, $config) {
        return new MyCustomDriver($name, $config);
    });
}

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.