README

A PHP package for building and parsing DMARC DNS records with a fluent, human-friendly API. Accepts readable values ('relaxed', 'strict', 'reject') and outputs correctly formatted DMARC strings.

Requirements

• PHP 8.3 or higher

This package has no runtime dependencies.

Installation

composer require cbowofrivia/dmarc-record-builder

Quick Start

use CbowOfRivia\DmarcRecordBuilder\DmarcRecord;

$record = (string) (new DmarcRecord())
    ->policy('reject')
    ->rua('mailto:dmarc@example.com');

// v=DMARC1; p=reject; rua=mailto:dmarc@example.com

Building a Record

Fluent API

All setter methods return $this, so calls can be chained:

$record = new DmarcRecord();

$record->policy('reject')
    ->subdomainPolicy('quarantine')
    ->rua('mailto:dmarc@example.com')
    ->ruf('mailto:dmarc-forensic@example.com')
    ->adkim('relaxed')
    ->aspf('strict')
    ->reporting(['dkim', 'spf'])
    ->nonExistentSubdomainPolicy('reject')
    ->publicSuffixDomainPolicy('y')
    ->testingMode('n');

echo $record;
// v=DMARC1; p=reject; sp=quarantine; rua=mailto:dmarc@example.com; ruf=mailto:dmarc-forensic@example.com; adkim=r; aspf=s; fo=d:s; np=reject; psd=y; t=n

Constructor

All parameters are optional. The constructor accepts the same values as the fluent setters:

$record = new DmarcRecord(
    version: 'DMARC1',
    policy: 'reject',
    subdomain_policy: 'quarantine',
    rua: 'mailto:dmarc@example.com',
    ruf: 'mailto:dmarc-forensic@example.com',
    adkim: 'relaxed',
    aspf: 'strict',
    reporting: ['dkim', 'spf'],
    np: 'reject',
    psd: 'y',
    t: 'n',
);

Static Factory

DmarcRecord::create() is a convenience wrapper around the constructor, useful when you want to build and cast in one expression:

$record = (string) DmarcRecord::create(
    policy: 'quarantine',
    rua: 'mailto:dmarc@example.com',
);

// v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com

Parsing an Existing Record

Pass a raw DMARC TXT record string to DmarcRecord::parse() to get a populated DmarcRecord object. This is useful for reading and modifying existing records.

$record = DmarcRecord::parse('v=DMARC1; p=quarantine; adkim=r; aspf=s; fo=d:s');

$record->policy;      // 'quarantine'
$record->adkim;       // 'relaxed'  (translated from 'r')
$record->aspf;        // 'strict'   (translated from 's')
$record->reporting;   // ['dkim', 'spf']  (translated from 'fo=d:s')

After parsing, you can modify the record and re-cast it to a string:

$record = DmarcRecord::parse('v=DMARC1; p=none; rua=mailto:dmarc@example.com');
$record->policy('reject');

echo $record;
// v=DMARC1; p=reject; rua=mailto:dmarc@example.com

parse() requires both v and p tags to be present and will throw an InvalidDmarcRecordException if either is missing. Unknown tags are silently ignored.

Tag Reference

Tags with a null value are omitted from the output string. Only v and p are always emitted.

Note: RFC 9989 (DMARCbis) removed the pct and ri tags, so this package no longer supports them (removed in 4.0.0). Records that still contain those tags parse without error — the tags are simply ignored.

Tag Details

policy() / subdomainPolicy() / nonExistentSubdomainPolicy()

Controls how the receiving mail server handles messages that fail DMARC checks.

• 'none' — take no action; useful during monitoring
• 'quarantine' — send to spam/junk
• 'reject' — reject the message outright

subdomainPolicy() (sp) overrides policy() for subdomains. If omitted, subdomains inherit the main policy.

nonExistentSubdomainPolicy() (np) applies to non-existent subdomains (RFC 9091 / DMARCbis). Takes precedence over both policy() and subdomainPolicy() for those domains.

rua() / ruf()

URIs for receiving DMARC reports. Must be prefixed with mailto:.

• rua — aggregate reports (daily summaries from receivers)
• ruf — forensic/failure reports (per-message failure details; not all receivers send these)

->rua('mailto:dmarc@example.com')
->ruf('mailto:dmarc-forensic@example.com')

Both tags also accept an array of addresses (RFC 9989 — comma-separated list):

->rua(['mailto:dmarc@example.com', 'mailto:backup@example.com'])
// rua=mailto:dmarc@example.com,mailto:backup@example.com

adkim() / aspf()

Alignment mode for DKIM and SPF respectively.

• 'relaxed' — the organisational domain must match (e.g. mail.example.com aligns with example.com)
• 'strict' — the domains must match exactly

Omitting either defaults to relaxed alignment per the RFC.

reporting()

Specifies which failure conditions trigger a forensic report. Accepts a string or an array of options:

Multiple values produce a colon-separated fo tag:

->reporting(['dkim', 'spf'])
// fo=d:s

->reporting(['any'])
// fo=1

Duplicate values are silently deduplicated. 'all' and 'any' are mutually exclusive — passing both throws an InvalidDmarcRecordException.

publicSuffixDomainPolicy()

Controls DMARC policy application at public suffix domains (DMARCbis extension).

• 'y' — apply DMARC policy to this public suffix domain
• 'n' — do not apply policy to this public suffix domain
• 'u' — undefined / unknown

testingMode()

When set to 'y', signals that DMARC is in testing mode. Receivers should not apply policy actions but may still send reports.

Validation

The package validates inputs on each setter call. Passing an invalid value throws a CbowOfRivia\DmarcRecordBuilder\Exceptions\InvalidDmarcRecordException. It extends the native \InvalidArgumentException, so existing catch (\InvalidArgumentException) handlers continue to work.

// Throws: Expected one of: "none", "quarantine", "reject", null. Got: "monitor"
$record->policy('monitor');

// Throws: rua mailto address should start with "mailto:"
$record->rua('dmarc@example.com');

// Throws: Expected one of: "relaxed", "strict", null. Got: "loose"
$record->adkim('loose');

// Throws: Reporting options "all" (0) and "any" (1) are mutually exclusive.
$record->reporting(['all', 'any']);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Charles Bowen
• All Contributors

License

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