Skip to content

Usage

Usage

The Cbox\LaravelDns\Facades\DomainConnect facade proxies the container-bound front door, so it uses the transport, signer, key host, and provider id from config/dns.php:

DomainConnect::discover(string $name, ?Template $template = null): Discovery
DomainConnect::applyUrl(ApplyRequest $request, ProviderSettings $settings): string
DomainConnect::recordSet(Template $template, Zone $zone, array $variables, array $groupIds = []): RecordSet
DomainConnect::check(RecordSet $set): Report
DomainConnect::outcome(array $query): ApplyOutcome

What each call does, the template model, and the signature are documented in the cboxdk/dns Domain Connect docs. Set DNS_DOMAIN_CONNECT_PROVIDER_ID and DNS_DOMAIN_CONNECT_PRIVATE_KEY first; see the config reference.

1. Discover when a domain is registered

use Cbox\Dns\DomainConnect\Template;
use Cbox\LaravelDns\Facades\DomainConnect;

$template = Template::fromJson(file_get_contents(resource_path('domain-connect/example.com.mail.json')));

$discovery = DomainConnect::discover($domain->name, $template);

$domain->update(['domain_connect' => $discovery->toArray()]);

Persist Discovery::toArray() and restore it later with Discovery::fromArray($domain->domain_connect), so the apply step does not repeat the lookups. $discovery->isAvailable() says whether the DNS provider offers the synchronous flow and $discovery->supportsTemplate() whether it knows your template; they are different answers.

2. Redirect the customer to their DNS provider

use Cbox\Dns\DomainConnect\ApplyRequest;
use Cbox\Dns\DomainConnect\Discovery;

$discovery = Discovery::fromArray($domain->domain_connect);

// Most hosts do not speak Domain Connect; settings is null for them.
abort_unless($discovery->isAvailable() && $discovery->settings !== null, 422);

$state = Str::random(40);
session(['domain_connect_state' => $state]);

$request = new ApplyRequest(
    template: $template,
    zone: $discovery->zone,
    variables: ['token' => $domain->dns_token],
    groupIds: [],
    redirectUri: route('domain-connect.callback'),
    state: $state,
);

return redirect()->away(DomainConnect::applyUrl($request, $discovery->settings));

applyUrl() throws a RuntimeException when no private key is configured, when DNS_DOMAIN_CONNECT_PROVIDER_ID is unset, or when it differs from the template's providerId.

3. Handle the return

Route::get('/domain-connect/callback', function (Request $request) {
    $outcome = DomainConnect::outcome($request->query());

    abort_unless(hash_equals((string) session('domain_connect_state'), (string) $outcome->state), 403);

    if (! $outcome->succeeded()) {
        return back()->withErrors(['domain' => $outcome->errorDescription ?? $outcome->error]);
    }

    // The redirect only says the customer did not cancel. Verify in DNS.
    CheckDomainConnectRecords::dispatch($domain)->delay(now()->addMinutes(2));

    return redirect()->route('domains.show', $domain);
})->name('domain-connect.callback');

4. Re-check the records

$discovery = Discovery::fromArray($domain->domain_connect);

$set = DomainConnect::recordSet($template, $discovery->zone, ['token' => $domain->dns_token]);
$report = DomainConnect::check($set);

$report->passed();

check() reads from the zone's authoritative nameservers, so it is the source of truth for whether the records are live. That needs the socket resolver: with resolver=doh there is no authoritative read and every record reports missing. The library's check() also does not take dns.allow_non_public_nameservers, so nameservers on private addresses are refused whatever that setting says.

What this package does not do

The package ships no routes. The callback route, validation of the state nonce (above, a session comparison), persistence of the discovery, and scheduling of the re-check belong to your application. The snippets above are a shape to adapt, not code the package provides.