Download the PHP package opusdns/php-client without Composer

OpusDNS PHP client

The official PHP client for the OpusDNS API: domain registration, transfers, renewals, contacts, DNS zones, email and domain forwarding, and everything else the API offers. The client is generated from the OpenAPI specification published in OpusDNS/api-spec, so every operation, model and enumeration of the API is available with full type information.

Requirements

• PHP 8.3 or newer
• A PSR-18 HTTP client and PSR-17 factories. Guzzle is used automatically when it is installed.
• An OpusDNS API key

Installation

Leave out guzzlehttp/guzzle if you provide your own PSR-18 client.

Quick start

Use Config::production() for the live API.

Configuration

Config::production($apiKey) and Config::sandbox($apiKey) are shortcuts for the two environments.

Every request carries the header X-OpusDNS-Client: opusdns-php-client/<version>.

Services

The API is grouped into services, one per tag of the specification. Each service is reached through an accessor on the client and has one method per operation, named after the operation id.

A few examples:

Method parameters follow the specification: path parameters first, then required query parameters and the request body, then optional query parameters. Optional parameters left at null are not sent. Named arguments keep calls readable:

Models

Every request and response schema is a final readonly class in OpusDNS\Client\Model, and every enumeration is a backed enum in OpusDNS\Client\Enum.

• Properties are public and camelCase: $domain->expiresOn, $zone->dnssecStatus. The JSON keys stay snake_case and are mapped by fromArray() and toArray().
• Construct request models with named arguments. Required fields come first and have no default; optional fields default to null or to the default the specification declares.
• Every service method that takes a body accepts either the model or a plain array with the JSON field names.
• Models implement JsonSerializable, so json_encode($domain) and framework JSON responses produce the API's own shape.
• toArray() omits properties that are null. new DomainUpdate(authCode: null) therefore leaves the auth code untouched. To send an explicit null, pass a plain array: updateDomain('example.com', ['auth_code' => null]).
• Enumerated fields are typed as the enum or its raw value, for example RenewalMode|string. Known values hydrate to the enum case, so $domain->renewalMode === RenewalMode::EXPIRE works; a value this version of the client does not know is kept as the raw string, so match expressions need a default arm.
• Timestamps are \DateTimeImmutable objects; they are sent as UTC RFC 3339 strings with a Z suffix. Date-only fields are \DateTimeImmutable objects at midnight UTC and are sent as YYYY-MM-DD, whatever the process timezone.
• Nested objects are models, lists are PHP lists and maps are string-keyed arrays, all documented with generic types in the constructor docblock. An empty map is sent as {}.
• Schemas that are a union of objects become PHP union types. The client resolves them with the discriminator the specification declares, or by matching required keys when there is none.

Pagination

Listing methods return a page model that implements Page: results() gives the items of that page and pagination() the metadata (currentPage, totalPages, totalItems, hasNextPage). Paginator walks all pages by calling your closure with successive page numbers.

Iteration stops when the API reports no further page, when the last page number is reached, when a page comes back empty, or after maxPages pages.

Errors

All exceptions extend OpusDNS\Client\Exception\OpusDnsException, which extends RuntimeException.

The status exceptions extend HttpException, which exposes statusCode(), the problem details the API sends (problemType, problemTitle, problemDetail), the decoded body, and the PSR-7 request and response. The stored request carries no X-Api-Key header.

Testing your integration

OpusDNS\Client\Testing\FakeHttpClient is a PSR-18 client that records requests and answers from a queue, so code using this client can be tested without the network:

queue() accepts any PSR-7 response or a throwable to simulate a transport failure. An empty queue answers 200 with an empty JSON object.

Lower-level access

Client::request() sends any request with the configured authentication and returns the PSR-7 response. Endpoint holds every path template of the API, and Permission::required() tells which permissions the API key needs for an operation.

Development

Layout

Examples

examples/ holds scripts that run against the sandbox and print what happens: registering, renewing and updating a domain. They read the key from the OPUSDNS_API_KEY environment variable or from a .env file in the repository root; copy .env.example to .env and fill in a sandbox key.

Commands

Updating to a new specification

Run composer spec:sync, then composer generate, composer test and composer stan, and review the diff of src/. New operations, models and enum values appear automatically; removed or renamed ones are a breaking change for consumers. Regenerate whenever the API adds enum values: hydration is strict, so a client built from an older specification keeps values it has never seen as raw strings.

The "Spec update" workflow does the same on a weekly schedule and on manual runs: it syncs the specification, regenerates, runs the checks and opens a pull request when anything changed. The "CI" workflow verifies on every push and pull request that src/ matches the committed specification and that the checks pass.

Releasing

Merging a pull request into main releases: the "Release" workflow runs the checks, bumps the version from the latest tag, pushes the new tag and creates the GitHub release with generated notes. The pull request's label picks the bump: major, minor or patch, with patch when no label is set; a no-release label skips the release. The same workflow can be run by hand with the bump chosen from a dropdown. Packagist picks the tag up through its GitHub hook.

How the generator maps the specification

License

Released under the MIT License. See LICENSE for the full text.