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;

Rendering a PDF instead

From SDK version 1.1, both request objects accept a format argument typed as the Format enum. Set it to Format::Pdf and the response url points at an A4 document instead of a PNG:

use Html2img\Enum\Format;
use Html2img\Request\HtmlRequest;

$response = $client->html(new HtmlRequest(
    html: '<h1>Invoice #1042</h1><p>Due within 30 days.</p>',
    format: Format::Pdf,
));

echo $response->url; // ends in .pdf

The PDF is vector output with selectable text and automatic pagination, and it costs the same single credit as an image. Sizing options such as width, height and dpi are ignored in PDF mode. See the format parameter docs for the full behaviour and the HTML to PDF API page for the overview.

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
}