Download the PHP package html-css-to-image/client without Composer

HTML/CSS to Image PHP Client

The official PHP client for the HTML/CSS to Image API. It provides immutable request and response models, signed URL helpers, and an injectable PSR-18 HTTP transport.

This README documents how the client behaves. The central API documentation is the source of truth for rendering features, parameter meanings, supported values, plan availability, and API limits. See the parameter reference when configuring a request.

Installation

PHP 8.2 or newer is required.

Quick start

Credentials are available in the HCTI dashboard. Keep the API key on a trusted server; never embed it in browser, desktop, or mobile application code.

Environment credentials

Set HCTI_API_ID and HCTI_API_KEY, then use:

fromEnvironment() throws RuntimeException when either variable is missing.

Requests and responses

Request constructors use PHP-style camelCase named arguments. The client maps them to the API's snake_case fields. null fields are omitted from JSON payloads; an explicit false is preserved for normal POST requests.

All supported fields are documented by property types and PHPDoc. Their API behavior is documented in the parameter reference, URL screenshot guide, and template guide.

createImage() returns either CreateImageSuccessResponse or ApiErrorResponse. Use instanceof to narrow the result to the appropriate response type. The success property remains available as a convenience. HTTP transport failures are raised by the PSR-18 client rather than converted into API responses, and a malformed successful API response raises UnexpectedValueException.

Batch requests

Only HTML/CSS and URL requests can be batched. Empty html or url values in variations are omitted so they can inherit from defaultOptions. An empty variation list returns a successful empty result without sending an HTTP request. Options unsupported by the batch API, such as dedupeDurationS, are not serialized. See the batch API documentation.

Signed URLs

The signed URL helpers perform no network request. They create the exact query string, sign it with HMAC-SHA256 using the API key, and return a URL that can be shared without exposing that key.

Use generateTemplatedImageUrl() when you already have a complete CreateTemplatedImageRequest. Use generateTemplatedImageUrlFromValues() as a convenience when you have a template ID and values. Both methods accept renderOptions.

Client behavior worth knowing:

• Render options are added before signing, so the signature covers the final query string.
• When both a request and its render options specify a format, the render option controls the signed URL path.
• Template fields that collide with render-option query names are assigned the API's reserved __ro_ names automatically.
• PDF layout options and deduplication options are omitted from create-and-render URLs because that endpoint does not support them.
• Custom URL headers become visible query parameters in a signed URL. Do not put secrets in them.

See the signed URL documentation for endpoint behavior and security considerations.

Image URLs and render options

imageUrl() builds a URL for an existing image without making a request:

Cropping uses immutable value objects and explicit factory methods:

The crop factories validate their inputs before generating a URL. Refer to the image URL and cropping documentation for transformation semantics and limits.

Deleting images

Every successful 2xx response maps to DeleteImageSuccessResponse. API errors use ApiErrorResponse, while network failures remain PSR-18 exceptions.

HTTP configuration

The default transport is a persistent Guzzle client with a 30-second timeout and no automatic retries. Inject any PSR-18 ClientInterface to configure timeouts, retries, proxies, certificates, connection limits, or test behavior:

The injected HTTP client remains caller-owned and is never closed or reconfigured by this package. Every API request includes HCTIPHP/<version> as its User-Agent, including requests sent through an injected client. Retry policy intentionally belongs to the application and can be added through the selected PSR-18 client's middleware or handler system.

Error handling

Client API

HtmlCssToImageClient implements HtmlCssToImageClientInterface. Public request, response, PDF, and render/crop classes include PHPDoc for their constructors, properties, parameters, return types, exceptions, and IDE help.

Development

Releasing

Packagist derives package versions from Git tags, so composer.json intentionally has no version field. To release, update VERSION in a pull request and merge it into main. After CI passes, the release workflow checks Packagist, creates the matching vX.Y.Z tag and GitHub Release when needed, and Packagist indexes the tag through its GitHub integration.

License

MIT