Login Get started
Get started
Login Get started
Home / Docs / Usage / HTML to Image PHP SDK

HTML to Image PHP SDK

The official PHP SDK wraps the HTML to Image REST API in a small, typed client so you don’t have to hand-roll cURL or Guzzle calls. It covers the HTML, screenshot and template endpoints, returns a typed response object, and throws specific exceptions for validation, authentication, rate-limit and credit errors.

Best for: any modern PHP or Laravel app that wants a maintained client with typed request objects. If you would rather call the API directly, see the raw PHP guide.

The SDK is open source on GitHub: html2img/html2img-php.

Requirements

  • PHP 8.3 or newer
  • The cURL extension (used by Guzzle under the hood)
  • An API key — see the quick start if you don’t have one yet

Installation

Install the package with Composer:

composer require html2img/html2img-php

Creating a client

Instantiate Html2img\Html2imgClient with your API key:

use Html2img\Html2imgClient;

$client = new Html2imgClient('your-api-key');

All constructor arguments beyond the API key are optional. Pass a custom base URI, timeout, or a pre-configured Guzzle instance if you need to:

use Html2img\Html2imgClient;

$client = new Html2imgClient(
    apiKey: 'your-api-key',
    baseUri: 'https://app.html2img.com',
    timeout: 35.0,
    httpClient: $guzzleInstance, // optional pre-configured Guzzle client
);

Store your API key in an environment variable rather than hard-coding it. In Laravel, read it from config('services.html2img.key'); in plain PHP, use getenv('HTML2IMG_API_KEY').

Converting HTML to an image

Pass an HtmlRequest to html(). The method returns a RenderResponse whose url property holds the CDN URL of the generated image:

use Html2img\Request\HtmlRequest;

$response = $client->html(new HtmlRequest(
    html: '<!doctype html><html><body><h1>Hello</h1></body></html>',
    width: 1200,
    height: 630,
    css: 'body { background: #0f172a; }',
    fullpage: true,
    dpi: 2,
));

echo $response->url; // CDN URL

Taking a screenshot

Use screenshot() with a ScreenshotRequest to capture a live URL. You can target a specific element with selector and inject CSS to hide elements such as cookie banners:

use Html2img\Request\ScreenshotRequest;

$response = $client->screenshot(new ScreenshotRequest(
    url: 'https://example.com',
    width: 1200,
    height: 630,
    selector: '#hero',
    css: '.cookie-banner { display: none !important; }',
    dpi: 2,
));

echo $response->url;

Rendering a template

Skip the HTML step entirely with a named template. Pass the template slug and a data array to template():

$response = $client->template('invoice', [
    'number' => 1042,
    'amount' => '$240.00',
    'due_date' => '2026-07-01',
]);

echo $response->url;

The response object

Every method returns a RenderResponse with the following properties and helpers:

MemberTypeDescription
successboolWhether the request succeeded
idstring|nullThe render ID
urlstring|nullCDN URL of the generated image
creditsRemainingint|nullCredits left on your account
statusstring|nullRender status
messagestring|nullError or status message
templatestring|nullTemplate slug, when a template was rendered
isProcessing()booltrue while an async job is still pending
raw()arrayThe full JSON payload

Error handling

All API errors throw Html2img\Exception\Html2imgException, with specific subclasses you can catch individually:

use Html2img\Exception\AuthenticationException;
use Html2img\Exception\InsufficientCreditsException;
use Html2img\Exception\RateLimitException;
use Html2img\Exception\ValidationException;
use Html2img\Exception\Html2imgException;

try {
    $response = $client->html(new HtmlRequest(html: '<h1>Hi</h1>'));
} catch (ValidationException $e) {
    // 422 — request parameters were invalid
} catch (AuthenticationException $e) {
    // 401 — bad or missing API key
} catch (InsufficientCreditsException $e) {
    // 402 — out of credits
} catch (RateLimitException $e) {
    // 429 — rate limit exceeded
} catch (Html2imgException $e) {
    // any other API error
}