Weave Code
Gotenberg Bundle Laravel Package
sensiolabs/gotenberg-bundle
Symfony bundle to generate PDFs and screenshots via the Gotenberg API. Convert from URL, HTML, Markdown, or Office files, then stream or save outputs locally. Supports source-specific options, advanced usage, and profiler/testing integrations.
A Symfony Bundle for interacting with Gotenberg. Integrates natively with twig, router, PHPStorm and more !
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?