Download the PHP package html2img/html2img-laravel without Composer

html2img for Laravel

The official Laravel integration for the HTML to Image API. Turn HTML and CSS into images, capture screenshots of live URLs, and render named templates, all behind a clean facade with zero-config auto-discovery.

It wraps the framework-agnostic html2img PHP SDK (source) and adds the Laravel pieces you would otherwise write yourself: a service provider, a published config file, a facade, container bindings, an artisan health check, and one-line saving of a render to any filesystem disk.

Every render runs in real Chrome, so flexbox, grid, custom properties, web fonts and inline JavaScript behave exactly as they do in the browser. The full API reference lives in the documentation, with a Laravel-specific guide at html2img.com/docs/usage/laravel.

Contents

• What you can build
• Requirements
• Installation
• Configuration
• Usage
  • Render HTML
  • Capture a screenshot
  • Generate a PDF
  • Render a template
• Saving renders to a disk
• Queues and jobs
• Render options
• The response
• Asynchronous delivery
• Error handling
• Verifying your setup
• Other languages
• Links

What you can build

• Open Graph and social images, generated per page or post. See the Open Graph image template and Twitter/X post template.
• Business documents such as invoices, receipts, event tickets and certificates.
• Developer assets such as code screenshots and GitHub social previews.
• URL screenshots, full page or cropped to a single element, with CSS injection to hide cookie banners and chat widgets before capture.

Browse the full template library, or try the no-signup browser tools to see the output before you write any code.

Requirements

• PHP 8.3 or newer
• Laravel 11 or 12
• A html2img API key, issued per account from your dashboard

Installation

The service provider and the Html2img facade are registered automatically through package discovery. Add your API key to .env:

That is the whole setup. See the authentication docs for issuing and rotating keys, and the getting started guide for a tour of the API.

Optionally publish the config file:

Configuration

The published config/html2img.php reads from your environment:

Custom HTTP client

The integration is built on Guzzle. To add your own retry middleware, logging or proxy settings, bind a configured GuzzleHttp\ClientInterface as html2img.http, for example in a service provider:

The package still sends the X-API-Key, Accept and Content-Type headers on every request.

Usage

Reach the API through the Html2img facade. Each method returns a readonly Html2img\Response\RenderResponse. The request objects come from the underlying SDK, so import them from the Html2img\Request namespace.

Render HTML

POST /api/html. Send a complete HTML document and get back an image of the rendered result. Inline your CSS in a <style> block, or reference remote stylesheets and web fonts via <link> tags in the document head. See the html parameter docs.

Rendering a Blade view into the image, as above, keeps your markup where the rest of your app lives.

Capture a screenshot

POST /api/screenshot. Fetch a public URL in a real browser and capture it. Use selector to crop to a single element, and css to hide cookie banners or chat widgets before the capture. See the url parameter docs and the selector docs.

Generate a PDF

Set format to Format::Pdf on either request and the render comes back as an A4 portrait vector PDF instead of a PNG: text stays selectable and searchable, webfonts are embedded and long content paginates automatically. The API ignores width, height, dpi, fullpage and selector in PDF mode, and the response url points at a .pdf file. One credit, the same as an image. See the format parameter docs.

Render a template

POST /api/v1/templates/{slug}. Render one of the built-in templates from a JSON data payload. The data is validated server-side per template. Templates output PNG only; format is not available on template renders.

Saving renders to a disk

The API returns the CDN URL of the image rather than the raw bytes, so you can cache and re-serve it from your own infrastructure. When you would rather keep a copy, store() downloads the image and writes it to any filesystem disk in one line:

You can also pass a URL string directly, or grab the raw bytes without storing them:

Queues and jobs

Renders are a natural fit for a queued job, especially full-page captures that take a few seconds. Resolve the facade or type-hint the manager:

For very large captures, prefer asynchronous delivery over a long-running job.

Render options

Both HtmlRequest and ScreenshotRequest accept the following. Any option left null is omitted from the request, so the server applies its own default. The complete reference is in the parameter docs.

ScreenshotRequest also accepts selector to crop the capture to a single element. HtmlRequest does not, since you control the markup.

Custom fonts are loaded by referencing them with <link> tags in your HTML document head, or by linking a web font from your captured page.

The response

Every method returns a readonly Html2img\Response\RenderResponse:

Asynchronous delivery

Synchronous requests have a 30 second budget. For captures likely to exceed it, pass a webhookUrl. The API responds immediately with status: "processing" and url: null, then POSTs the final image URL to your endpoint once rendering finishes. See the webhook_url docs.

Error handling

Every failure throws an Html2img\Exception\Html2imgException. Catch that single type to handle any error, or catch a specific subclass. No raw Guzzle exception escapes the package.

Verifying your setup

Confirm your key and configuration with the bundled artisan command, which renders a small test image:

It prints the resulting image URL and your remaining credits, or a clear error if the key is missing or rejected. The check uses one credit. There is also a testing guide for the API itself.

Other languages

Not on Laravel? The same API has worked guides for plain PHP, Ruby on Rails, Python, JavaScript and Node.js, React and Vue.

Development

This package uses ddev for a containerised PHP environment. It is optional, and you can use vanilla PHP or whatever you use for local dev if you prefer.

Links

Website · Documentation · Laravel guide · Templates · Tools · Features · Comparisons · Articles · Pricing · PHP SDK

Licence

MIT. See LICENSE.