Gotenberg Php Laravel Package

Technical Evaluation

Architecture fit: gotenberg/gotenberg-php is a framework-agnostic PHP client for a separately deployed Gotenberg 8.x service. It fits Laravel/PHP applications as a thin adapter around PSR-7 requests and PSR-18 HTTP clients, not as a Laravel-native package. TPM value is clear: it lets the team add HTML/URL/Office-to-PDF, screenshots, PDF/A, merge/split, and related document workflows without building Chromium/LibreOffice orchestration in-house. The trade-off is a new runtime dependency: a Gotenberg container/service must be deployed, secured, monitored, and upgraded.

Integration feasibility: High for a Laravel team already using Composer and Guzzle/PSR-18. The package is small, MIT-licensed, documented, and release notes show active alignment with Gotenberg versions. Laravel integration would be a thin internal wrapper: config entry for the Gotenberg API URL, singleton binding for the PSR-18 client, and a service class that builds/sends requests. There is no official Laravel bundle; the Symfony bundle is not directly reusable. The package requires PHP 8.1+ for v2 and a PSR-18 adapter such as php-http/guzzle7-adapter.

Technical risk: Moderate. Primary risks are operational, not PHP-level: Gotenberg container CVEs/upgrades, Chromium/LibreOffice resource consumption, conversion timeouts, large-file handling, and SSRF exposure if user-supplied URLs are converted. Community adoption signals are modest: 403 stars and 0 dependents, though the package is maintained under the official Gotenberg organization. Version lock-step with Gotenberg 8.x means upgrade planning must cover both client and service. The supplied 2026 release date should be verified against Packagist/GitHub before committing to a release cadence assumption.

Key questions: What document types and volumes must be supported? What are the latency and availability SLOs? Are PDF/A, PDF/UA, screenshots, or merge/split required? Will users supply URLs, or only trusted internal content? Where will Gotenberg run—Docker Compose, Kubernetes, VM, or managed container platform? Who owns Gotenberg upgrades, fonts, LibreOffice compatibility, and on-call? Is there an existing PDF stack to migrate from, and what golden-file/regression testing exists?

Integration Approach

Stack fit: Add gotenberg/gotenberg-php and a PSR-18 adapter via Composer. In Laravel, bind Psr\Http\Client\ClientInterface to Guzzle, add GOTENBERG_API_URL to environment config, and expose a small internal service such as DocumentConversionService. Use Gotenberg::send() when streaming a response to the browser or API consumer, and Gotenberg::save() when writing to a Laravel storage disk or temp directory. Heavy conversions should run through Laravel queues, not synchronously in web requests.

Migration path: Containerize Gotenberg in local, CI, staging, and production before application rollout. Start with one low-risk use case—invoice/report PDF generation or a single Office-document conversion—and run it in parallel with the existing generator. Compare output against golden files, then migrate use cases incrementally. Avoid a big-bang replacement of an existing PDF pipeline.

Compatibility: The client targets Gotenberg 8.x with v2.x. Confirm Laravel version, PHP version, Guzzle/PSR-18 adapter compatibility, and deployment platform support. Laravel’s HTTP client is not the integration surface here; use a PSR-18-compatible Guzzle client. Pin both the PHP package and Gotenberg container image, and test upgrades together.

Sequencing: 1) Confirm use cases, SLOs, and data/security constraints. 2) Stand up Gotenberg in a non-production environment. 3) Add Composer dependencies and Laravel config/service bindings. 4) Build an internal wrapper with correlation IDs, timeouts, and error mapping. 5) Implement queued conversion jobs and storage cleanup. 6) Add health checks, metrics, and dashboards. 7) Pilot with one workflow. 8) Roll out by use case with rollback to the prior PDF path.

Operational Impact

Maintenance: The PHP client itself should be low-maintenance. The real maintenance burden is the Gotenberg service: container image upgrades, Chromium/LibreOffice security patches, font packages, and compatibility testing for document rendering. Treat Gotenberg as a production service with an owner, upgrade cadence, and pinned versions.

Support: Open-source support only unless the organization buys commercial support elsewhere. There is no SLA from the package. Internal runbooks should cover Gotenberg restarts, stuck conversions, queue backlogs, correlation-ID lookup, and fallback behavior. The Symfony bundle signal is useful but does not provide Laravel support.

Scaling: Gotenberg is CPU- and memory-heavy during conversion. Scale it horizontally behind an internal service endpoint and scale Laravel queue workers separately. Enforce concurrency limits, request timeouts, max file sizes, and temp-storage quotas. Use correlation IDs (Gotenberg-Trace) to connect Laravel logs to Gotenberg logs.

Failure modes: Gotenberg unavailable; conversion timeout; Chromium/LibreOffice crash or OOM; malformed or password-protected documents; unsupported fonts; disk-full on temp storage; SSRF via user-supplied URLs; version mismatch after upgrade; and queue saturation. Mitigations include health checks, circuit breaking, bounded retries with backoff, dead-letter queues, input validation, URL allow-lists, output-size limits, and a fallback PDF path during pilot.

Ramp-up: PHP/Laravel developers can learn the client quickly because the API is small and fluent. Infrastructure and SRE ramp-up is moderate: Docker/Kubernetes networking, resource limits, observability, and document-rendering regression testing. Budget for a proof of concept and load test before production commitment. Overall, this is a good leverage package when the organization needs robust document conversion and can operate Gotenberg; it is a poor fit for low-volume teams unwilling to run and maintain the service.