Download the PHP package poli-page/sdk without Composer

Poli Page SDK for PHP

Official PHP SDK for Poli Page — render polished PDFs from HTML templates via the Poli Page API.

→ Docs (auto-generated from source): https://poli-page.github.io/sdk-php/

Install

The SDK declares only PSR-18 / PSR-17 / PSR-3 interfaces plus php-http/discovery as hard dependencies — it deliberately ships no concrete HTTP client. You must install a PSR-18 client and a PSR-7 / PSR-17 implementation alongside it, or constructing the client will throw (discovery finds nothing to use). Install both in one command:

Guzzle bundles its own PSR-7 / PSR-17 implementation, so that single line is everything you need. Prefer something else? Any PSR-18 client + PSR-7 pairing works:

Discovery auto-detects whichever you've installed; you never name it in code (or pass it explicitly via the httpClient: constructor argument — see Configuration).

Requires PHP 8.3 or later.

Quick start

Project mode — render a published template by slug

Every Poli Page org comes pre-provisioned with a getting-started/welcome template, so the snippet above runs as-is the moment you have an API key — no project setup needed. For your own templates, swap the slugs once you've pushed a version with the poli CLI:

Preview inline HTML

render->preview accepts raw HTML for live editing and visual inspection without producing a stored document. Use this for editor previews or layout tests.

render->pdf, render->pdfStream, and render->document require project mode — project + template, optionally pinned to a specific version (omit to render the current draft). Inline HTML is only accepted by render->preview. The SDK enforces this via PHP's type system: ProjectModeInput and InlineModeInput are final readonly classes extending a sealed RenderInput base; the three document-producing methods type-hint ProjectModeInput, so passing inline mode is a TypeError. PHPStan / Psalm also catch the mismatch statically.

Write a PDF to disk

renderToFile streams response bytes directly to disk in 8 KB chunks (bounded memory regardless of document size).

Try it locally — runnable demo

The repo ships a single end-to-end demo that exercises every public method against the real API:

First run prompts for a pp_test_* key and saves it to .env. Subsequent runs are silent. See examples/demo.php for the full walkthrough.

Stream — for large PDFs or piping to S3 / HTTP responses

Any PSR-7-aware destination works — write to a file, an HTTP response body, or an S3 multipart upload that accepts a stream.

Working with stored documents

Every render produces a stored document, accessible via documentId for later download or thumbnails. render->pdf and render->pdfStream are conveniences that chain a presigned-URL fetch internally to return bytes; render->document returns just the descriptor (skip the auto-download when you'll fetch the bytes later).

The presigned URL has a 15-minute TTL. If downloadPdf() fails with errorCode: 'DOWNLOAD_FAILED' (HTTP 403 from S3), call documents->get($id) to refresh and retry.

Authentication & environments

The mode is determined by the API key prefix:

• pp_test_… → sandbox mode (not billed, generous rate limits)
• pp_live_… → live mode (billed, production rate limits)
• pp_sa_… → service-account keys; environment matches the SA's configuration (sandbox or live)

All prefixes hit the same endpoint (https://api.poli.page). The SDK passes the key through as a Bearer token and never inspects the prefix — pick whichever fits your deploy model.

Methods

Configuration

Construct via the static factory for the common case, or use the named-argument constructor when you want to override anything:

Per-call overrides live on the input object itself: pass timeout: and/or idempotencyKey: to ProjectModeInput / InlineModeInput to override the client-level defaults for that one call.

Error handling

The SDK ships a small exception hierarchy under PoliPage\Exception, all rooted in PoliPageException. Idiomatic PHP usage is catch by subclass:

The hierarchy:

Predicate helpers are kept for spec parity across SDK languages:

For lifecycle and billing failures, route the user to actionable messages rather than treating them as opaque errors:

→ Full error reference: https://poli-page.github.io/sdk-php/reference/errors/

Cancellation

PHP has no first-class cancellation primitive (no AbortSignal, no context.Context). The SDK exposes timeouts instead:

• timeout: on the constructor — applied as the per-request deadline for every call.
• timeout: on the input object (ProjectModeInput / InlineModeInput) — overrides the client default for that one call.

PSR-18 does not standardise per-request timeouts, so the SDK forwards the value to the underlying client where possible (Guzzle, Symfony HTTP Client) and otherwise documents it as a best-effort hint. Configure connect / total timeouts on your injected PSR-18 client for guaranteed enforcement.

Observability

PSR-3 logger (logger: constructor argument)

Works with Laravel's Log facade, Symfony's LoggerInterface autowiring, Monolog standalone, or any custom PSR-3 implementation. The SDK emits one DEBUG line per HTTP attempt, one INFO per success, one WARN per retry, and one ERROR per terminal failure. The Authorization header is never logged.

SDK-level hooks (onRetry, onError)

Hooks fire at well-defined points; they are sync, optional, and never break the request:

For per-request / per-response inspection, install middleware on your injected PSR-18 client (Guzzle handler stack, Symfony HTTP Client decoration, etc.) — that's the cross-framework PHP convention and the SDK deliberately doesn't reinvent it.

Retries & idempotency

The SDK retries on 5xx, 429, network errors, and timeouts. Backoff is exponential (retryDelay × 2^attempt) with jitter in [0.5, 1.5], capped by Retry-After when the server provides it (max 30 s). Every POST sends an auto-generated Idempotency-Key (UUID v4); pass idempotencyKey: in the input to override.

Type system

The SDK is fully type-annotated and tested at PHPStan level max with phpstan-strict-rules. Every public method has explicit parameter and return types; PHPDoc array shapes are provided wherever native PHP types are insufficient.

RenderInput is a sealed-in-package abstract class with exactly two concrete subclasses — ProjectModeInput and InlineModeInput. The render methods type-hint the specific subclass they accept, so invalid combos (passing inline-mode HTML to render->pdf) fail at compile-time (PHPStan) and runtime (PHP TypeError).

final readonly class is used throughout for input/output DTOs. Mutations require constructing a new instance — pair with PHP 8.4's clone with syntax if you need a one-field tweak.

Concurrency & thread-safety

PHP's per-request execution model means client instances are scoped to a single request — there is no shared mutable state to coordinate across requests. For long-running workers (ReactPHP, Swoole, RoadRunner, FrankenPHP), construct one client per worker rather than sharing across requests, since the underlying PSR-18 client may not be reentrant.

Runtime support

The SDK is sync-only. PHP request lifecycles are typically short-lived; concurrent rendering — if you need it — is handled at the application layer (Symfony Process, ReactPHP / Amp, PHP-FPM workers).

Requirements

• PHP 8.3 or later
• A PSR-18 HTTP client + PSR-17 factories (Guzzle, Symfony HTTP Client, etc.)

Documentation & support

• Platform docs: docs.poli.page
• SDK docs site: poli-page.github.io/sdk-php
• Sign up & generate API keys: app.poli.page
• Issues: github.com/poli-page/sdk-php/issues

License

MIT © Poli Page