README

Official PHP SDK for the HTML to PDF API. One package — works in any PHP 8.1+ project and ships with first-class Laravel integration (service provider, facade, publishable config).

HtmlToPdf::html('<h1>Invoice #001</h1>...')
    ->paperSize('a4')
    ->margins(top: 25, bottom: 25)
    ->footer('<div class="text-center">Page <span class="pageNumber"></span></div>')
    ->generate()
    ->saveAs(storage_path('invoices/001.pdf'));

Why this SDK

• Fluent builder, one method per API field — ->margins(...), ->waitForSelector(...), ->retina() — discoverable in any IDE
• Typed exceptions — ValidationException::errors() maps the API's per-field errors so they slot into existing form-error flows
• Client-side validation — obvious typos fail with \InvalidArgumentException before the HTTP round-trip
• Laravel auto-discovery — composer require and you're done; facade, service provider, and config are wired automatically
• Zero hidden state — no globals, no static configuration; everything is injected through the constructor

Compatibility

The full Laravel × PHP test matrix lives in .github/workflows/ci.yml — every combination below runs on every PR:

Laravel < 8 (i.e. 6.x / 7.x): not tested. The SDK has no Laravel-version-specific code and only touches stable ServiceProvider / Facade APIs, so it may work — but you'd also need PHP 8.1+ (which Laravel 6/7 don't officially support), and we don't run CI against it. Use at your own risk.

The SDK does not require Laravel — composer require htmltopdfapi/php-sdk in a vanilla PHP project works fine.

Install

composer require htmltopdfapi/php-sdk

Set your API key

Create one in the dashboard and add to your .env (Laravel) or environment (plain PHP):

HTML_TO_PDF_API_KEY=sk_live_xxxxxxxxxxxxxxxx

Configuration reference

Laravel

The service provider auto-discovers; nothing else to do. Optionally publish the config to customise programmatically:

php artisan vendor:publish --tag=html-to-pdf-config

Plain PHP

use HtmlToPdfApi\HtmlToPdf;

$sdk = new HtmlToPdf([
    'api_key'  => getenv('HTML_TO_PDF_API_KEY'),
    'base_url' => 'https://platform.htmltopdfapi.co/api/v1', // optional
    'timeout'  => 60,                                    // optional
]);

Quick start

Laravel — Blade view to inline PDF response

use HtmlToPdfApi\Laravel\Facades\HtmlToPdf;

Route::get('/invoices/{invoice}.pdf', function (Invoice $invoice, Request $request) {
    $html = view('invoices.pdf', compact('invoice'))->render();

    return HtmlToPdf::html($html)
        ->paperSize('a4')
        ->margin(20)
        ->footer('<div style="text-align:center;font-size:9px">Page <span class="pageNumber"></span></div>')
        ->generate()
        ->toResponse($request);
});

Plain PHP — URL to file on disk

$sdk->url('https://example.com/dashboard')
    ->landscape()
    ->waitUntil('networkidle0')
    ->retina()
    ->generate()
    ->saveAs('/tmp/dashboard.pdf');

Save to disk and attach to an email (Laravel)

$path = storage_path("app/invoices/{$invoice->number}.pdf");

HtmlToPdf::html(view('invoices.pdf', compact('invoice'))->render())
    ->paperSize('a4')
    ->margin(20)
    ->generate()
    ->saveAs($path);

Mail::to($invoice->customer->email)
    ->send(new InvoiceEmail($invoice, $path));

More recipes: examples/ + docs/.

Cookbook

API reference

Entry point

use HtmlToPdfApi\Laravel\Facades\HtmlToPdf; // Laravel
// or
use HtmlToPdfApi\HtmlToPdf;                 // Plain PHP
$sdk = new HtmlToPdf(['api_key' => '...']);

Builder

Every method returns $this for chaining and validates input client-side.

Reserved CSS classes inside header(...) / footer(...) are substituted by Chromium at render time:

PdfResponse

Returned by generate():

$pdf->bytes();              // string   — raw PDF bytes
$pdf->base64();             // string   — base64-encoded (inline embed)
$pdf->size();               // int      — byte length
$pdf->filename();           // string   — parsed from Content-Disposition, or null
$pdf->saveAs(string $path); // bool     — writes to disk; throws on failure
$pdf->stream();             // resource — caller must fclose()
$pdf->headers();            // array    — raw response headers
$pdf->toResponse($request); // Illuminate\Http\Response (Laravel only)

Error handling

Every SDK exception extends HtmlToPdfApi\Exceptions\HtmlToPdfException:

HtmlToPdfException
├── ConnectionException       network / DNS / TLS / timeout — usually retryable
├── AuthenticationException   401 — bad / missing API key
├── ValidationException       422 — exposes ->errors(): array<string, string[]>
├── UsageLimitException       429 — plan quota
└── ServerException           5xx — usually retryable with backoff

use HtmlToPdfApi\Exceptions\ValidationException;

try {
    $pdf = HtmlToPdf::html('...')->margins(top: 999)->generate();
} catch (ValidationException $e) {
    foreach ($e->errors() as $field => $messages) {
        report("[{$field}] " . $messages[0]);
    }
}

Full pattern reference: docs/error-handling.md.

Testing

Running the SDK's own tests

composer install
./vendor/bin/phpunit
./vendor/bin/pint --test

Faking the SDK in consumer tests

A built-in HtmlToPdf::fake() helper is planned for 0.2. Until then, mock the Client and bind it through the container:

$client = Mockery::mock(\HtmlToPdfApi\Client::class);
$client->shouldReceive('generatePdf')->andReturn(new \HtmlToPdfApi\PdfResponse('%PDF-fake'));

$this->app->instance(\HtmlToPdfApi\HtmlToPdf::class, new \HtmlToPdfApi\HtmlToPdf(
    new \HtmlToPdfApi\Config(['api_key' => 'sk_test']),
    $client,
));

Versioning

This SDK follows Semantic Versioning. The public surface — builder method signatures, exception classes, PdfResponse methods — won't break in patch or minor releases. Pre-1.0 versions may introduce changes; pin to ^0.1 to be safe.

The SDK version is exposed at \HtmlToPdfApi\HtmlToPdf::VERSION and is sent in the User-Agent header on every API call.

Roadmap

Things planned for upcoming releases (in rough order):

• Screenshot endpoint binding (PNG / JPEG / WebP) — when the API ships it
• HtmlToPdf::fake() test helper
• Rendered-HTML endpoint binding
• Async generation + webhook receiver helper
• PSR-3 logger integration
• PHPStan / Larastan static analysis

Contributing

Bug reports and PRs welcome. Before sending a PR:

./vendor/bin/phpunit
./vendor/bin/pint

Both should pass.

License

MIT. See LICENSE.