Zactonz PHP SDK

Calling an endpoint#

Every method takes named arguments that mirror the endpoint's parameters. Leave one out and it is not sent.

$page    = $zactonz->markdown()->fromUrl(url: 'https://example.com/article', maxChars: 20000);
$records = $zactonz->domain()->dns(name: 'example.com', type: ['A', 'MX', 'TXT']);
$days    = $zactonz->domain()->ssl(host: 'example.com')['days_remaining'];
$checked = $zactonz->email()->verify(emails: ['jane@example.com', 'sales@example.com']);

Reading results#

Methods return a Zactonz\Result.

$preview = $zactonz->links()->preview(url: 'https://zactonz.com');

$preview['title'];                   // a field
$preview->get('image.url');          // a nested field, null when absent
$preview->data;                      // the whole payload
$preview->rateLimit->remaining;      // requests left this minute
$preview->rateLimit->dayRemaining;   // units left today
$preview->requestId();               // for support requests

Most endpoints return an object whose fields you read directly. Three return a single value, available as $result->data: the screenshot() methods return a link, with width and height readable as fields; qr()->decode() returns the decoded text; drive()->directLink() returns a URL.

Files#

A method whose name ends in File returns the bytes as a Zactonz\File rather than a link.

$zactonz->barcode()->encodeFile(content: 'ZCTZ-0042')->save('label.png');

$card = $zactonz->og()->generateFile(title: 'Ship faster', theme: 'dark');
$card->contentType;   // image/png
$card->dataUri();     // for an <img src>

download() fetches a link that came back in a result, and only ever over HTTP or HTTPS:

$pdf = $zactonz->screenshot()->captureHtml(html: $invoiceHtml, format: 'pdf');
$zactonz->download($pdf->data)->save('invoice.pdf');

To upload a local image, pass its path:

$zactonz->image()->convertFile(file: 'photo.jpg', format: 'webp', width: 800)->save('photo.webp');

Links to generated files are public to anyone who has them and expire. How long each lasts is on the endpoint's reference page.

Signed image URLs#

An og:image tag cannot send an Authorization header, so the OG Image endpoint also accepts a signed URL. SignedUrl::og() builds one from the key id and signing secret shown in the console. No request is made until something fetches the image.

use Zactonz\SignedUrl;

$url = SignedUrl::og($keyId, $secret, [
    'title'    => $post->title,
    'subtitle' => $post->excerpt,
    'theme'    => 'dark',
]);

Testing your code#

Zactonz\Testing\FakeTransport replaces the network. Queue the responses your code should receive and inspect the requests it made.

use Zactonz\Client;
use Zactonz\Testing\FakeTransport;

$transport = new FakeTransport(
    FakeTransport::json(['status' => 200, 'data' => ['qr' => 'https://api.zactonz.com/qr/enc/i/x.png']]),
);
$zactonz = new Client('zk_qr_test', maxRetries: 0, transport: $transport);

$zactonz->qr()->encode(content: 'hello');

$transport->lastRequest()->url;   // https://api.zactonz.com/qr/enc/?content=hello&resp=json

Your own HTTP client#

Requests go through Zactonz\Http\Transport, a one-method interface. Implement it to route requests through your own HTTP client, proxy or logging, and pass it as transport. An implementation must not follow redirects.