Checks catalog

The findings model

Each check returns zero or more Findings. A Finding carries:

Severity means:

• Error — a misconfiguration that breaks resolution, mail, or trust.
• Warning — works today, but fragile, non-redundant, or below best practice.
• Info — an observation or a healthy result worth surfacing.

Report::passed() is a clean bill of health: no errors and no warnings.

The default catalog

Diagnostics::run() executes these checks, in report order. Every check turns a DNS-level failure into a Finding rather than throwing.

The DKIM check (opt-in)

DKIM cannot be probed without knowing the selector — there is no way to enumerate selectors over DNS — so DkimCheck is not in the default set. Run it explicitly with a selector via runWith():

use Cbox\Dns\Diagnostics\Diagnostics;
use Cbox\Dns\Diagnostics\Checks\DkimCheck;

$diagnostics = new Diagnostics($dns->resolver());

$report = $diagnostics->runWith('example.com', [new DkimCheck('selector1')]);
// checks selector1._domainkey.example.com -> dkim.presence / dkim.revoked

Adding your own checks

A check implements Cbox\Dns\Diagnostics\Contracts\Check:

use Cbox\Dns\Diagnostics\Contracts\Check;
use Cbox\Dns\Diagnostics\DiagnosticContext;
use Cbox\Dns\Diagnostics\Finding;

final class MyCheck implements Check
{
    /** @return list<Finding> */
    public function run(DiagnosticContext $ctx): array
    {
        $addresses = $ctx->addresses($ctx->domain);   // resolved via the injected resolver

        return $addresses === []
            ? [Finding::warning('Custom', 'my.check', 'Apex has no A/AAAA.')]
            : [Finding::info('Custom', 'my.check', count($addresses).' apex addresses.')];
    }
}

DiagnosticContext exposes the target domain plus the injected collaborators — resolver, authoritative, dnssec, propagation — and helpers nameservers() and addresses($host). Run a custom list, optionally alongside the defaults:

$diagnostics->runWith('example.com', [
    ...Diagnostics::defaultChecks(),
    new MyCheck,
]);