Weave Code
Gotenberg Bundle Laravel Package
sensiolabs/gotenberg-bundle
Symfony bundle that generates, streams, and saves PDFs and screenshots from URLs, HTML, Markdown, or Office files via the Gotenberg API. Includes a profiler and testing helpers.
SensioLabs Gotenberg Bundle integrates the Gotenberg API into Symfony to generate, stream, and save PDF documents locally from URLs, HTML, Markdown, or Office files, and to capture screenshots from URLs, HTML, and Markdown. Configuration comes ready out of the box with Symfony Flex, including a Docker setup, and the bundle supports both basic and advanced usage patterns.
- Generate and save PDFs from HTML, Markdown, URLs, or Office documents
- Capture images with configurable screenshot options
- Flexible per-request options depending on the source type
- Built-in Symfony Profiler panel for debugging requests
- First-class testing utilities for reliable test suites
Frequently asked questions about Gotenberg Bundle
- Can I use this bundle directly in Laravel without Symfony, or do I need to install Symfony components?
- This bundle is Symfony-first, but you can adapt it for Laravel by replacing Symfony’s HttpClient with Laravel’s HTTP facade or the standalone `symfony/http-client` package. Twig can be replaced with Blade via a custom adapter, and Symfony’s config system can be mapped to Laravel’s `.env` and `config/gotenberg.php`. Docker orchestration remains the same.
- How do I configure Gotenberg’s DSN (e.g., Docker URL) in Laravel’s `.env` file?
- Add `GOTENBERG_DSN=http://gotenberg:3000` to your `.env` file, then create a `config/gotenberg.php` file to define additional settings like `assets_directory`, `timeout`, or `default_options`. The bundle’s Symfony config can be translated to Laravel’s format with minimal effort.
- Will this bundle work with Laravel’s Blade templating instead of Twig?
- Yes, but you’ll need to create a Blade adapter for the `gotenberg_asset()` function or replace Twig-specific logic with Laravel’s `asset()` helper. The core PDF/screenshot generation remains unchanged, as it relies on Gotenberg’s API, not templating engines.
- How do I deploy Gotenberg alongside Laravel in Docker? Does it conflict with Laravel’s services?
- Add Gotenberg to your `docker-compose.yml` alongside Laravel’s services (e.g., `gotenberg` service with ports `3000:3000`). Use Docker networks to ensure Laravel containers can communicate with Gotenberg. Resource limits (CPU/memory) should be set in `docker-compose.yml` to avoid conflicts.
- What Laravel versions and PHP versions are officially supported?
- The bundle requires PHP 8.2+ and Symfony 6.4+, but it can integrate with Laravel 10+ by replacing Symfony dependencies. Test thoroughly with your Laravel version, as some Symfony-specific features (e.g., Twig) may need workarounds.
- How do I handle long-running PDF generation tasks to avoid blocking Laravel’s PHP workers?
- Queue PDF generation jobs using Laravel’s queue system (e.g., `dispatch(new GeneratePdfJob($data))`). Process jobs asynchronously with `queue:work`, and return a job ID to the user. Gotenberg’s API timeouts can be configured in `config/gotenberg.php`.
- Are there Laravel-native alternatives to this bundle for PDF/screenshot generation?
- Yes, alternatives like `barryvdh/laravel-dompdf` (PDF-only) or `spatie/pdf-to-image` (screenshots) are Laravel-specific. However, GotenbergBundle offers broader format support (Markdown, Office files) and Chromium-based rendering, which may justify its use despite the Symfony dependency.
- How do I mock Gotenberg in Laravel’s PHPUnit/Pest tests?
- Use the bundle’s existing mock utilities (e.g., `GotenbergPdfInterface` mocks) with Laravel’s testing tools. For Pest, extend the mock setup with `Pest::mock('GotenbergPdfInterface', fn() => ...)`. Ensure your test container binds the mock to Laravel’s service container.
- What happens if Gotenberg’s API fails (e.g., timeout, invalid input)? How do I handle errors in Laravel?
- Gotenberg’s API errors (e.g., 500 responses) will throw exceptions. Catch these in Laravel’s exception handler (`app/Exceptions/Handler.php`) and log them. Configure retries or fallback behavior in `config/gotenberg.php` (e.g., `max_retries`).
- Can I use this bundle for production-scale PDF generation without performance issues?
- Gotenberg’s Chromium-based conversion is resource-intensive. Scale by limiting concurrent requests (e.g., queue jobs), setting Docker resource limits, and monitoring CPU/memory usage. For high traffic, consider a dedicated Gotenberg cluster or serverless deployment.
Weaver
How can I help you explore Laravel packages today?