Gotenberg PHP

gotenberg-php is the official PHP SDK for Gotenberg, a self-hosted, developer-friendly API that wraps Chromium, LibreOffice, and other conversion engines to turn HTML, Markdown, Office documents (Word, Excel, PowerPoint), and more into PDFs, screenshots, or merged documents. Rather than shelling out to wkhtmltopdf or LibreOffice directly, applications send an HTTP request to a running Gotenberg instance, and this client builds that request with a fluent, module-based API.

The package models each Gotenberg conversion route (Chromium HTML/URL-to-PDF, Chromium screenshots, LibreOffice document conversion, PDF engine operations like merging or metadata embedding) as a typed request-builder class, and dispatches the resulting multipart request through any PSR-18 HTTP client via php-http/discovery, making it framework-agnostic while still shipping first-class Laravel and Symfony integration examples.

What You Get

• Fluent request builders for Chromium PDF/screenshot conversion, LibreOffice document conversion, and PDF Engines operations (merge, split, flatten, metadata)
• A Stream helper for converting in-memory content or uploaded files into the multipart payload Gotenberg expects
• Gotenberg::save() and Gotenberg::send() helpers for either writing results directly to disk or getting a PSR-7 response
• PSR-18 HTTP client discovery via php-http/discovery, so it works with Guzzle or any other PSR-compatible client already in the project
• Support for advanced Gotenberg features like Factur-X e-invoice embedding, custom cookies for Chromium, and configurable PDF split modes

Common Use Cases

• Converting user-submitted HTML or a rendered Blade/Twig view into a downloadable PDF invoice or report
• Generating PDF screenshots of a target URL for archiving, previews, or automated visual testing
• Converting uploaded Word, Excel, or PowerPoint documents to PDF for consistent cross-platform viewing
• Merging multiple generated PDFs (e.g. a cover page plus a converted document) into a single output file via the PDF Engines module

Under The Hood

Architecture — The package centers on Gotenberg.php as the entry point, which returns one of several Module implementations (Chromium, LibreOffice, PdfEngines) exposing a fluent per-route builder; each builder accumulates form fields and file streams into a MultipartFormDataModule, which Gotenberg::send()/save() serializes into a PSR-7 request and dispatches through a discovered PSR-18 client, with the raw HTTP response returned to the caller or streamed directly to a file path. Supporting classes (Stream, DownloadFrom, EmbedMetadata, FacturX, SplitMode) model individual Gotenberg options as typed value objects rather than raw arrays. Tech Stack — PHP 8.1–8.5, built on guzzlehttp/psr7 for PSR-7 message objects and php-http/discovery for locating an available PSR-18 HTTP client at runtime, keeping the package decoupled from any single HTTP client implementation. Code Quality — A dedicated PHPUnit test suite (ApiModuleTest, GotenbergTest, MultipartFormDataModuleTest, StreamTest, SplitModeTest, FacturXTest) with per-module coverage under tests/Modules, phpstan static analysis, phpcs style enforcement, and Codecov-tracked coverage in CI, indicating disciplined maintenance for a relatively small (240KB) but widely-depended-upon client library. API Design — The module-per-route design (Gotenberg::chromium($url)->pdf()->url(…), Gotenberg::libreOffice($url)->convert(…)) mirrors Gotenberg’s own HTTP route structure closely, so developers already familiar with the Gotenberg API reference can map documentation examples to PHP method calls almost one-to-one, minimizing translation friction between API docs and code.