Download the PHP package kasperhartwich/quickdns without Composer

QuickDNS

A PHP client for QuickDNS.dk. Manage zones, templates and groups from code: create and delete zones, attach them to templates and groups, and list what the account holds.

QuickDNS has no public API, so the client logs in with the account's email and password and talks to the same endpoints as the QuickDNS website.

Requirements

• PHP 8.3 or later

Installation

Upgrading from 2.x? UPGRADING.md lists what changed in 3.0.

Usage

The client logs in on its first request, not when it is created, so it can be built long before it is used, for example in a service container. Wrong credentials throw QuickDns\Exceptions\LoginFailed from that first request. Call login() to check them right away:

QuickDNS ends a login session after a while. When a request is answered with the login page, the client logs in again and sends that request once more, so a long-lived client keeps working. In the middle of an edit it cannot: the pending changes went with the old session, so the edit throws UnrecognisedPage and nothing is saved.

To send the requests through your own Guzzle client (middleware for logging or rate limiting, or a MockHandler in tests), pass it as the third argument. QuickDns keeps the login session cookies itself, so the client needs no cookie jar:

Zones

Zones, templates and groups are immutable. create(), rename(), addZone() and removeZone() return the new state as a new object, and the object you called them on keeps describing what it was read as.

Records

Each QuickDns\Record has name (as QuickDNS shows it: @, www, *), type, ttl and priority (null when blank), value, row (the record's row on the zone page) and template (the template that added the record, or null). isLocked() is true for template records: they can only be changed on the template itself.

Writing records

edit() runs one QuickDNS edit session: every change is sent as it is made, and the lot is saved when the closure returns.

Find records with find(name:, type:, value:), where(...) or sole(...), which throws unless exactly one matches. all() returns them in page order, and the set is iterable and countable.

Nothing is saved unless everything works. If the closure throws, or QuickDNS rejects a change, the session is discarded. That is QuickDNS' own behaviour: it saves nothing from a session that holds a rejected record, not even the changes it accepted.

For a single change there are one-shot helpers, each its own session:

What QuickDNS accepts, checked against the service:

A record that breaks one of the first four rules throws InvalidRecord before anything is sent. What only QuickDNS can judge throws RecordRejected, which carries its Danish messages in errors(), the rows in rows() and the records in records().

Templates and groups

Each of these reads the zone's current templates or groups from QuickDNS first, because QuickDNS replaces the whole list, and returns the zone as QuickDNS shows it afterwards.

A zone can use several templates, and $zone->templates lists their names. $zone->templates(), $zone->groups(), $template->zones() and $template->groups() read the related objects themselves, and $template->zoneCount says how many zones use a template. To set the whole list at once, by name, id or object:

Template and Group also have create(), delete() and rename(), just like Zone. QuickDNS does not answer with a new group's id, so a group's create() reads the groups page to find it.

A group's members are the QuickDNS users it is shared with, as QuickDns\Member objects with id, name, email and confirmed (false while an invitation is not accepted).

A template's records

A template holds records of its own, and every zone using it gets them. They read and write exactly like a zone's, and on the zone they show up as locked:

A template's records are applied to each zone exactly as they are written. Nothing is rewritten:

• Names are relative to the zone. @ is the zone's apex, www is www. plus the zone, and * is the wildcard. On a zone, the template row www A 192.0.2.2 shows as www A 192.0.2.2, locked.
• @ is the only placeholder. As a value it also means the zone's apex, so alias CNAME @ and @ MX @ work on every zone. There is no {domain}, $DOMAIN or similar. On a zone, a value containing {, } or $ is rejected ("indeholder ugyldige tegn").
• Any other target is literal. A CNAME, MX or NS target outside the zone needs its trailing dot (mail.example.dk.). QuickDNS refuses a CNAME to a bare name such as www.

A template can be saved and still be unusable. The template page checks less than a zone does, so a record the zone would refuse is only caught when the template is applied. Then addZone() and setTemplates() throw CommandFailed ("De valgte skabeloner giver 1 fejl i zonen"). Nothing is applied, and the zone keeps the templates it had. Records added to a template that zones already use show up on those zones straight away.

Example: set up several domains from one template

Errors

Every exception from QuickDNS extends the abstract QuickDns\Exceptions\QuickDnsException:

Using the library wrongly, such as starting an edit inside another, throws LogicException instead: that is a bug to fix, not something QuickDNS said.

CommandFailed also says what failed: function() is the command, status() QuickDNS' status, statusText() its message and fields() the rest of its answer.

Laravel

The service provider is discovered automatically. Set the account in .env:

and use QuickDns\QuickDns from the container (it logs in on first use), or the facade:

php artisan vendor:publish --tag=quickdns-config publishes config/quickdns.php, where client can name a container binding of a GuzzleHttp\ClientInterface to send the requests with. In tests, QuickDns::fake() swaps in a FakeQuickDns and returns it.

Symfony

Register the bundle in config/bundles.php:

and configure it in config/packages/quickdns.yaml:

QuickDns\QuickDns is then autowirable. It logs in on first use.

Testing your code

QuickDns\Testing\FakeQuickDns is an in-memory quickdns.dk. It keeps zones, templates, groups and records and answers with the same pages as QuickDNS, so code that uses this package can be tested without the network:

The fake writes records too, with the same rules, the same locked template rows and the same all-or-nothing saving. $fake->failNextChange('...') makes the next change fail the way QuickDNS would, and $fake->hasPendingChanges('example.dk') shows whether an edit was left open.

Like QuickDNS, every new zone gets four NS records from the template "QuickDNS global". To keep your own middleware, use the fake as the handler: HandlerStack::create($fake).

Testing this package

runs the offline test suite against recorded QuickDNS pages. No account needed.

The live suite creates and deletes real zones, templates and groups, so run it against a dedicated test account, never one in use:

License

MIT. See LICENSE.txt.

Contributing

Pull requests are welcome.