Gotenberg Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dgarden/gotenberg-bundle
   

   Ensure sensiolabs/gotenberg-bundle is also installed (dependency).

2. Configuration Add the required configs to:

   • config/packages/dgarden_gotenberg.yaml (output path)
   • config/routes/dgarden_gotenberg.yaml (routes)
   • config/packages/gotenberg.yaml (Gotenberg API connection via sensiolabs/gotenberg-bundle).

3. First Use Case Generate a PDF from HTML in a controller:

   use SensioLabs\GotenbergBundle\Client\GotenbergClientInterface;
   use SensioLabs\GotenbergBundle\Model\ConvertDocumentRequest;
   
   public function generatePdf(GotenbergClientInterface $client)
   {
       $request = new ConvertDocumentRequest();
       $request->setSource('html', '<h1>Hello, PDF!</h1>');
       $response = $client->convert($request);
   
       return new Response($response->getContent(), 200, [
           'Content-Type' => 'application/pdf',
       ]);
   }
   

Implementation Patterns

Common Workflows

1. PDF Generation from HTML Use ConvertDocumentRequest to convert HTML strings or URLs to PDFs:

   $request = new ConvertDocumentRequest();
   $request->setSource('html', $htmlContent);
   $client->convert($request);
   

2. PDF Generation from URLs

   $request->setSource('url', 'https://example.com');
   

3. Saving PDFs Locally Leverage dgarden_gotenberg.output_path to auto-save PDFs:

   dgarden:
     gotenberg:
       output_path: '%kernel.project_dir%/var/pdf'
   

   Then use the bundle’s service to handle file storage.

4. Queueing PDF Jobs Use Symfony’s Messenger component to offload PDF generation:

   $message = new GeneratePdfMessage($html, $outputPath);
   $bus->dispatch($message);
   

5. Custom Metadata Extend sensiolabs/gotenberg-bundle config for PDF metadata:

   sensiolabs_gotenberg:
       default_options:
           pdf:
               html:
                   metadata:
                       Author: 'Your App'
                       Title: 'Dynamic PDF'
   

Integration Tips

• Twig Integration: Pass HTML from Twig templates directly to the client.
• API Endpoints: Create dedicated routes for PDF generation (e.g., /api/pdf).
• Validation: Validate HTML/URL inputs before processing to avoid malformed PDFs.
• Error Handling: Wrap GotenbergClientInterface calls in try-catch blocks for API failures.

Gotchas and Tips

Pitfalls

1. Missing Dependencies Ensure sensiolabs/gotenberg-bundle is installed and configured. The dgarden bundle relies on it for core functionality.

2. Output Path Permissions If output_path is set, ensure the directory is writable:

   mkdir -p var/pdf && chmod -R 775 var/pdf
   

3. Gotenberg Service Unavailable The API must be running (Docker setup recommended). Test connectivity:

   curl -X POST http://localhost:3000/forms/chromium/convert/url -F 'url=https://example.com'
   

4. HTML/URL Size Limits Gotenberg has payload size limits. For large content, stream data or split into chunks.

5. Caching Responses PDF generation can be slow. Cache responses (e.g., with Symfony’s cache system) for repeated requests.

Debugging

• Logs: Enable debug mode (APP_DEBUG=true) to inspect Gotenberg API responses.
• Network Tab: Check the GotenbergClient HTTP requests in browser dev tools for errors.
• Docker Health: Verify Gotenberg container logs:

  docker logs gotenberg
  

Tips

1. Dynamic Filenames Use uniqid() or UUIDs to avoid filename collisions in output_path:

   $filename = 'pdf_' . uniqid() . '.pdf';
   

2. Async Processing For long-running tasks, use Symfony’s Messenger with a queue (e.g., RabbitMQ):

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               async: '%env(MESSENGER_TRANSPORT_DSN)%'
   

3. Custom Templates Store reusable HTML templates in a templates/pdf/ directory and load them dynamically:

   $html = $twig->render('pdf/template.html.twig', ['data' => $data]);
   

4. Environment-Specific Config Override gotenberg.yaml per environment (e.g., local vs. production DSN):

   # config/packages/gotenberg_prod.yaml
   sensiolabs_gotenberg:
       http_client: 'gotenberg.client.prod'
   

5. Extension Points Extend the bundle by creating custom services that wrap GotenbergClientInterface for domain-specific logic (e.g., InvoicePdfGenerator).