# PHP SDK

> Learn how to generate images and PDFs with the bannerify/bannerify Composer package.

Canonical: https://bannerify.co/docs/sdk/php/overview

`bannerify/bannerify` is the Bannerify client for PHP 8.1 and later. It uses Guzzle and returns errors as values, so a failed request does not throw.

## Install

```bash
composer require bannerify/bannerify
```

## Create a client

You need an API key. Create one on the **API Keys** page of the dashboard and keep it on the server.

```php
<?php

require 'vendor/autoload.php';

use Bannerify\Client;

$client = new Client(getenv('BANNERIFY_API_KEY'));
```

## Generate an image

```php
$result = $client->createImage('tpl_xxx', [
    'modifications' => [
        ['name' => 'headline', 'text' => 'Summer sale'],
    ],
]);

if (isset($result['error'])) {
    throw new RuntimeException($result['error']['message']);
}

file_put_contents('banner.png', $result['result']);
```

`$result['result']` is a string that holds the image bytes.

## Methods

| Method | Result | Use it to |
| --- | --- | --- |
| `createImage` | Bytes | Get the image bytes |
| `createPdf` | Bytes | Get a PDF |
| `createStoredImage` | URL string | Get a hosted image URL |
| `renderVideo` (Beta) | `Generator` of events | Render a video and follow its progress |
| `renderAndWaitVideo` (Beta) | URL string | Render a video and get its MP4 URL |
| `createVideo` (Beta) | Created video array | Start a video and get its id at once, without waiting |
| `getVideo` (Beta) | Video array | Read the status and the MP4 URL of a video by its id |
| `watchVideo` (Beta) | `Generator` of events | Follow the progress of a video again by its id |
| `generateImageSignedUrl` | URL string | Build a link that renders when someone opens it |

[Create images and PDFs](https://bannerify.co/docs/sdk/php/apis/create-image) covers the first three, [Render videos](https://bannerify.co/docs/sdk/php/apis/render-video) covers the video methods, and [Signed URL](https://bannerify.co/docs/sdk/php/apis/signed-url) covers the last one.

## Handle errors

Every method except `generateImageSignedUrl` returns an array with a `result` key or an `error` key, and never both.

```php
['result' => '...']

['error' => ['code' => 'NOT_FOUND', 'message' => '...', 'docs' => '...', 'requestId' => '...']]
```

An error from the API has all four keys. `docs` links to the page for that code, and you send `requestId` to support when you need help with a request. [Errors](https://bannerify.co/docs/api-reference/errors/introduction) lists the codes.

The SDK creates a few errors itself. They have `code`, `message`, and `docs`, but no `requestId`.

| Code | Meaning |
| --- | --- |
| `INVALID_FORMAT` | The format is not `png`, `jpeg`, or `webp` |
| `REQUEST_ERROR` | The request failed before the API answered, for example when the connection dropped or the request ran past the timeout |
| `HTTP_ERROR` | The API answered with an error that the SDK could not read |
| `TIMEOUT_ERROR` | A video stream dropped and the SDK could not read the video again |
| `EXCEPTION` | Any other exception inside the SDK. `message` holds its text |

`generateImageSignedUrl` returns a string and throws `InvalidArgumentException` when the format is not supported.

## Options

```php
$client = new Client(getenv('BANNERIFY_API_KEY'), [
    'timeout' => 30,
]);
```

| Option | Default | Description |
| --- | --- | --- |
| `baseUrl` | `https://api.bannerify.co/v1` | The API base URL |
| `timeout` | `60.0` | Request timeout in seconds |

## Learn more

- [Generate dynamic images in PHP](https://bannerify.co/blog/generate-images-php): render banners and product images with cURL or this SDK.
- [Dynamic invoice PDFs from JSON in PHP](https://bannerify.co/blog/dynamic-invoice-pdf-php): fill a table from your billing data and get a hosted PDF link.

## Related

- [Previous: Signed URLs in JavaScript](https://bannerify.co/docs/sdk/js/apis/signed-url)
- [Next: Create images and PDFs in PHP](https://bannerify.co/docs/sdk/php/apis/create-image)
- [Documentation index](https://bannerify.co/docs/llms.txt)