# Zactonz PHP SDK: Usage

> PHP client for the Zactonz APIs: QR codes and barcodes, screenshots and PDFs, social card images, image conversion, link previews, page to Markdown, SSL, DNS, WHOIS, email checks and translation.

Page: https://developers.zactonz.com/tools/zactonz-php/usage/

Complete documentation for this product: https://developers.zactonz.com/tools/zactonz-php.md

## Calling an endpoint

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

```php
$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`.

```php
$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.

```php
$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:

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

To upload a local image, pass its path:

```php
$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](https://developers.zactonz.com/apis/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.

```php
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.

```php
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.