omnisense/omnidns API reference

Omnidns

AvailabilityInterface interface

interface AvailabilityInterface extends ProviderInterface AvailabilityInterface.php:8

Whether a domain can be registered here, and at what price.

AvailabilityInterface::check()

public function check(string $domain): Availability

Capabilities class

final readonly class Capabilities Capabilities.php:6

What a provider can be asked, said before it is asked anything, and whose terms apply.

public bool $availability

whether a domain is free, its price (AvailabilityInterface)

public bool $registrar

registering and renewing (RegistrarInterface)

public bool $domains

the account's domains and their terms (DomainsInterface)

public bool $nameservers

a domain's name servers (NameserversInterface)

public bool $dns

a zone's records (DnsInterface)

public array $recordTypes

the record types its DNS takes

public array $terms

the terms whoever runs it must follow (URLs)

Capabilities::__construct()

public function __construct(public bool $availability = false, public bool $registrar = false, public bool $domains = false, public bool $nameservers = false, public bool $dns = false, public array $recordTypes = [], public array $terms = [])

$availability

whether a domain is free, its price (AvailabilityInterface)

$registrar

registering and renewing (RegistrarInterface)

$domains

the account's domains and their terms (DomainsInterface)

$nameservers

a domain's name servers (NameserversInterface)

$dns

a zone's records (DnsInterface)

$recordTypes

the record types its DNS takes

$terms

the terms whoever runs it must follow (URLs)

Capabilities::contracts()

public function contracts(): array

Returns

what it can be asked, by contract

Capabilities::toArray()

public function toArray(): array

Config class

final class Config extends ArrayObject Config.php:14

A provider's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Config::string()

public function string(string $key): ?string

A string option; null when it is empty.

Config::int()

public function int(string $key, int $default = 0): int

Config::float()

public function float(string $key, float $default = 0.0): float

Config::bool()

public function bool(string $key): bool

A boolean option, as an environment variable gives it too: "1", "true", "yes", "on".

DnsInterface interface

interface DnsInterface extends ProviderInterface DnsInterface.php:12

The records of a zone the provider serves. A record is found by its id when the provider gives one, else by its name, type and content (Record::sameAs()).

DnsInterface::records()

public function records(string $zone, ?string $type = null, ?string $name = null): array

$type

a record type ("MX"); null: every type

$name

a name relative to the zone ("" for the apex); null: every name

DnsInterface::add()

public function add(string $zone, Record $record): Record

Returns

the record added, with its id when the provider gives one

DnsInterface::update()

public function update(string $zone, Record $current, Record $new): Record

Returns

the record as it now is

DnsInterface::delete()

public function delete(string $zone, Record $record): void

DomainsInterface interface

interface DomainsInterface extends ProviderInterface DomainsInterface.php:8

The domains the account holds, and each one's term.

DomainsInterface::domains()

public function domains(): array

DomainsInterface::domain()

public function domain(string $domain): DomainInfo

NameserversInterface interface

interface NameserversInterface extends ProviderInterface NameserversInterface.php:6

The name servers a registered domain delegates to.

NameserversInterface::nameservers()

public function nameservers(string $domain): array

Returns

host names, no trailing dot

NameserversInterface::setNameservers()

public function setNameservers(string $domain, array $nameservers): void

ProviderFactory class

abstract class ProviderFactory implements ProviderFactoryInterface ProviderFactory.php:15

A provider's factory fills a Config - its name ("omnidns.factory_name"), its title ("omnidns.factory_title"), the options it needs ("omnidns.required_options") and the defaults of the others - then builds the provider from it.

Nothing here calls anything: a factory whose provider is reached over HTTP takes its client in its own constructor - the application's, a MockHttpClient in a test.

ProviderFactory::getName()

public function getName(): string

ProviderFactory::create()

public function create(array $options = []): ProviderInterface

ProviderFactory::createConfig()

public function createConfig(array $options = []): Config

ProviderFactoryInterface interface

interface ProviderFactoryInterface ProviderFactoryInterface.php:6

Builds a provider from its options (a key, a token...).

ProviderFactoryInterface::getName()

public function getName(): string

The name providers are configured with: "ovh", "cloudflare".

..

ProviderFactoryInterface::create()

public function create(array $options = []): ProviderInterface

ProviderInterface interface

interface ProviderInterface ProviderInterface.php:13

One provider where domains are registered or their DNS is served, configured: OVH, Gandi, Cloudflare, Scaleway... Its Capabilities say what it can be asked - is a domain free (AvailabilityInterface), register or renew it (RegistrarInterface), the domains the account holds and when they end (DomainsInterface), their name servers (NameserversInterface), the records of a zone (DnsInterface) - and whose terms apply.

ProviderInterface::getName()

public function getName(): string

The factory's name: "ovh", "gandi", "cloudflare", "scaleway".

..

ProviderInterface::getTitle()

public function getTitle(): string

ProviderInterface::capabilities()

public function capabilities(): Capabilities

RegistrarInterface interface

interface RegistrarInterface extends ProviderInterface RegistrarInterface.php:13

Registering a domain and renewing it - orders that cost money: each provider says in its README whether the order is paid at once (the account's means of payment) or waits for a payment at Order::$paymentUrl.

RegistrarInterface::register()

public function register(string $domain, int $years = 1, ?Contact $owner = null): Order

$owner

the registrant; null: the account's default contact, where the provider has one

RegistrarInterface::renew()

public function renew(string $domain, int $years = 1): Order

Registry class

final class Registry Registry.php:24

The application's domain and DNS providers by name, each built once from its factory and options:

$registry = new Registry([new OvhFactory(), new CloudflareFactory()], [ 'registrar' => ['factory' => 'ovh', 'options' => ['application_key' => '...', 'application_secret' => '...', 'consumer_key' => '...']], 'dns' => ['factory' => 'cloudflare', 'options' => ['token' => '...']], ]);

$registry->availability('registrar')->check('example.org')->available; $registry->dns('dns')->records('example.org', 'MX');

A typed getter gives the provider when it implements the interface and its capabilities() say it gives that as configured (Cloudflare lists domains only with an account_id): otherwise a NotSupportedException.

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): ProviderInterface

Registry::has()

public function has(string $name): bool

Registry::availability()

public function availability(string $name): AvailabilityInterface

The provider, as the availability of a domain.

Registry::registrar()

public function registrar(string $name): RegistrarInterface

The provider, as a registrar.

Registry::domains()

public function domains(string $name): DomainsInterface

The provider, as the account's domains.

Registry::nameservers()

public function nameservers(string $name): NameserversInterface

The provider, as a domain's name servers.

Registry::dns()

public function dns(string $name): DnsInterface

The provider, as a zone's records.

Registry::options()

public function options(string $name): array

Returns

the options a provider is configured with

Registry::names()

public function names(): array

Returns

the configured providers' names

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

Omnidns\Exception

InvalidArgumentException class

final class InvalidArgumentException extends InvalidArgumentException implements OmnidnsException InvalidArgumentException.php:6

A value no provider can take: a malformed domain name, a record type unknown, a duration of zero years.

InvalidConfigException class

final class InvalidConfigException extends InvalidArgumentException implements OmnidnsException InvalidConfigException.php:6

A provider asked for with options it cannot work with, or not configured at all.

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnidnsException NotSupportedException.php:6

A provider asked for what it cannot give: a registration asked of a provider that only hosts DNS.

NotSupportedException::capability()

public static function capability(object $provider, string $name, string $capability): self

OmnidnsException interface

interface OmnidnsException extends Throwable OmnidnsException.php:6

Every exception omnidns throws.

ProviderException class

final class ProviderException extends RuntimeException implements OmnidnsException ProviderException.php:6

The provider answered, and not with what was asked: an error status, a domain not in the account, an order refused.

ProviderException::answered()

public static function answered(string $provider, string $what, int|string $status, int $code = 0): self

$code

the HTTP status when the provider answered with one, as the exception's code

UnreachableException class

final class UnreachableException extends RuntimeException implements OmnidnsException UnreachableException.php:6

The provider could not be reached: a network error, a timeout.

Omnidns\Http

Json class

final class Json Json.php:15

A JSON request on the application's HTTP client, its failures turned into omnidns's exceptions (an empty answer is an empty array); and typed reads of what came back, for providers that walk an answer they do not control.

Json::request()

public static function request(HttpClientInterface $http, string $method, string $url, array $options, string $provider, string $what): array

$options

the client's options (headers, json, query...)

Returns

the decoded answer

Json::get()

public static function get(mixed $data, string|int ...$path): mixed

The value at a path of keys; null when any step is missing.

Json::string()

public static function string(mixed $data, string|int ...$path): ?string

A non-empty string at the path, or null.

Json::int()

public static function int(mixed $data, string|int ...$path): ?int

Json::bool()

public static function bool(mixed $data, string|int ...$path): bool

Json::list()

public static function list(mixed $data, string|int ...$path): array

Returns

the list at the path; empty when there is none

Json::date()

public static function date(mixed $data, string|int ...$path): ?\DateTimeImmutable

A date at the path, or null.

Redaction class

final class Redaction Redaction.php:22

What a failed call may carry of its credentials, taken out before the failure leaves the package: an HTTP client's exception quotes the URL called (a key in its query, a password in its user part), and every exception's trace keeps the arguments of the calls under it (the request options, headers and query with the key) unless PHP runs with zend.exception_ignore_args.

copy() gives the previous exception to wrap instead of the client's own: the same class and code, its message with the key's parameters, the user part and every secret value replaced by ***, its trace without arguments, its own previous copied the same way. Properties of the client's class beyond those of \Exception are not copied (a Symfony HttpException's response, a PSR-18 exception's request: their URL holds the key). withoutArguments() takes the arguments out of the trace of the exception thrown in its place.

const MASK = '***'

Redaction::secrets()

public static function secrets(string $url, array $options = []): array

The secrets a request carries: the values of its query parameters, headers and body fields named as credentials (key, token, secret, password, signature, auth...), a bearer token, a basic password, the URL's user part.

$options

the HTTP client's options

Redaction::sensitive()

public static function sensitive(string $name): bool

Whether a parameter, header or field of this name holds a credential.

Redaction::text()

public static function text(string $text, array $secrets = []): string

A text without credentials: in every address, the user part and the parameters named as credentials masked (api_key=***); then every secret given, raw or URL-encoded, masked wherever it stands.

Redaction::copy()

public static function copy(\Throwable $failure, array $secrets = []): \Throwable

A copy of a failure to wrap in its place: its class, code, file and line, its message through text(), its trace without arguments, its previous copied the same way.

Redaction::withoutArguments()

public static function withoutArguments(\Throwable $failure): \Throwable

The failure given, the arguments out of its trace (and out of its previous ones'), as zend.exception_ignore_args would have left it.

Omnidns\Model

Availability class

final readonly class Availability Availability.php:10

Whether a domain can be registered, and at what price when the provider quotes one: the first year's (Gandi: before taxes; OVH: its "TOTAL"), and the renewal's when it says.

public string $domain

public bool $available

public ?Money $price

public ?Money $renewal

public bool $premium

public ?string $reason

Availability::__construct()

public function __construct(public string $domain, public bool $available, public ?Money $price = null, public ?Money $renewal = null, public bool $premium = false, public ?string $reason = null)

Availability::toArray()

public function toArray(): array

Contact class

final readonly class Contact Contact.php:10

The domain's owner (registrant), as a registry needs them - or a contact the provider already holds, named by its handle (an OVH /me/contact id, a Scaleway contact id): then the rest may stay empty.

const INDIVIDUAL = 'individual'

const COMPANY = 'company'

const ASSOCIATION = 'association'

public string $firstName

public string $lastName

public string $email

public string $phone

in the registries' form: +33.123456789

public string $street

public string $city

public string $zip

public string $country

ISO 3166-1 alpha-2: FR

public string $type

public ?string $organization

public ?string $handle

Contact::__construct()

public function __construct(public string $firstName = '', public string $lastName = '', public string $email = '', public string $phone = '', public string $street = '', public string $city = '', public string $zip = '', public string $country = '', public string $type = self::INDIVIDUAL, public ?string $organization = null, public ?string $handle = null)

$phone

in the registries' form: +33.123456789

$country

ISO 3166-1 alpha-2: FR

Contact::handle()

public static function handle(string $handle): self

Contact::toArray()

public function toArray(): array

DomainInfo class

final readonly class DomainInfo DomainInfo.php:10

A domain the account holds, as its registrar shows it: when it ends, whether it renews itself, its statuses, its name servers when the provider gives them in the same answer (null: ask NameserversInterface).

public string $name

public ?\DateTimeImmutable $expiresAt

public ?bool $autoRenew

public array $status

the registry's or the provider's statuses: "ok", "clientTransferProhibited"...

public ?array $nameservers

public ?\DateTimeImmutable $createdAt

DomainInfo::__construct()

public function __construct(public string $name, public ?\DateTimeImmutable $expiresAt = null, public ?bool $autoRenew = null, public array $status = [], public ?array $nameservers = null, public ?\DateTimeImmutable $createdAt = null)

$status

the registry's or the provider's statuses: "ok", "clientTransferProhibited"...

DomainInfo::daysLeft()

public function daysLeft(?\DateTimeImmutable $now = null): ?int

Days left before it ends (negative once it has); null when the provider does not say.

DomainInfo::toArray()

public function toArray(): array

DomainName class

final class DomainName DomainName.php:8

A domain name as every provider is asked it: lower case, no trailing dot, labels a registry accepts.

DomainName::normalize()

public static function normalize(string $name): string

Money class

final readonly class Money Money.php:8

A price in hundredths of its currency's unit (8.39 EUR: 839), and its ISO 4217 currency.

public string $currency

public int $cents

Money::__construct()

public function __construct(public int $cents, string $currency)

Money::fromDecimal()

public static function fromDecimal(string|int|float $amount, string $currency): self

From a decimal amount: "636.28", 636.28, 5.

Money::decimal()

public function decimal(): string

"636.28"

Money::multiply()

public function multiply(float $factor): self

Money::toArray()

public function toArray(): array

Order class

final readonly class Order Order.php:9

What a registration or a renewal left with the provider: its order or task, its state, its price and, when it waits for a payment, where to pay.

const REGISTER = 'register'

const RENEW = 'renew'

public string $domain

public string $action

public string $status

public ?string $id

public ?Money $price

public ?string $paymentUrl

public int $years

Order::__construct()

public function __construct(public string $domain, public string $action, public string $status, public ?string $id = null, public ?Money $price = null, public ?string $paymentUrl = null, public int $years = 1)

Order::toArray()

public function toArray(): array

Record class

final readonly class Record Record.php:16

One DNS record of a zone: its type, its name relative to the zone ("" for the apex, "www", "_dmarc"), its content (an address, a host, a text), its TTL (null: the zone's default) and, for MX, its priority apart. A provider that names records gives its id; one that groups them by name and type (Gandi's rrsets) gives none, and a record is then known by its name, type and content. Options are what one provider keeps besides (Cloudflare's "proxied"), handed back to it on an update.

const TYPES = ['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NS', 'SRV', 'TXT']

public string $type

public string $name

public string $content

public ?int $ttl

public ?int $priority

public ?string $id

public array $options

Record::__construct()

public function __construct(string $type, string $name, public string $content, public ?int $ttl = null, public ?int $priority = null, public ?string $id = null, public array $options = [])

Record::normalizeName()

public static function normalizeName(string $name): string

A name relative to its zone as records hold it: lower case, no trailing dot, "" for the apex ("@").

Record::fromValue()

public static function fromValue(string $type, string $name, string $value, ?int $ttl = null, ?string $id = null, array $options = []): self

A record from a provider that writes an MX's priority in its value ("10 mx.example.org.").

Record::value()

public function value(): string

The value as a zone file writes it: an MX's priority before its host.

Record::fqdn()

public function fqdn(string $zone): string

The record's full name in a zone: "www.example.org", "example.org" for the apex.

Record::relative()

public static function relative(string $name, string $zone): string

A name a provider gives in full ("www.example.org"), relative to the zone ("www").

Record::sameAs()

public function sameAs(self $other): bool

The same record: the same id when both have one; else the same name, type and content (a host's trailing dot and a text's quotes aside).

Record::findIn()

public function findIn(iterable $records): ?self

The one of these records that is the same as this one.

Record::withId()

public function withId(?string $id): self

Record::toArray()

public function toArray(): array

Omnidns\Testing

MemoryFactory class

final class MemoryFactory extends ProviderFactory MemoryFactory.php:17

MemoryProvider, from its options:

domains the domains held, and when each ends: ["example.org" => "2027-03-01"] taken the domains held by someone else price a year's price, as a Model\Money

Options

MemoryProvider class

final class MemoryProvider implements AvailabilityInterface, RegistrarInterface, DomainsInterface, NameserversInterface, DnsInterface MemoryProvider.php:25

A registrar and a DNS host in memory, every contract answered: for tests, demos and an application's fixtures. A domain registered is held for the years asked, served by ns1/ns2.memory.test, its zone empty.

MemoryProvider::__construct()

public function __construct(array $domains = [], readonly array $taken = [], readonly ?Money $price = null, readonly \DateTimeImmutable $now = new \DateTimeImmutable('2026-01-01'))

$domains

the domains held, and when each ends ("2027-03-01")

$taken

the domains held by someone else

MemoryProvider::getName()

public function getName(): string

MemoryProvider::getTitle()

public function getTitle(): string

MemoryProvider::capabilities()

public function capabilities(): Capabilities

MemoryProvider::check()

public function check(string $domain): Availability

MemoryProvider::register()

public function register(string $domain, int $years = 1, ?Contact $owner = null): Order

MemoryProvider::renew()

public function renew(string $domain, int $years = 1): Order

MemoryProvider::domains()

public function domains(): array

MemoryProvider::domain()

public function domain(string $domain): DomainInfo

MemoryProvider::nameservers()

public function nameservers(string $domain): array

MemoryProvider::setNameservers()

public function setNameservers(string $domain, array $nameservers): void

MemoryProvider::records()

public function records(string $zone, ?string $type = null, ?string $name = null): array

MemoryProvider::add()

public function add(string $zone, Record $record): Record

MemoryProvider::update()

public function update(string $zone, Record $current, Record $new): Record

MemoryProvider::delete()

public function delete(string $zone, Record $record): void