Gotenberg Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Symfony Native Integration: Seamlessly integrates with Symfony’s dependency injection, Twig templating, and HTTP client stack, reducing boilerplate for PDF/screenshot generation.
  • Modular Design: Supports diverse input types (URLs, HTML, Markdown, Office docs, etc.) via specialized builders (UrlPdfBuilder, HtmlPdfBuilder, etc.), aligning with Laravel’s service-oriented architecture if adapted via Symfony’s bridge (e.g., Laravel Symfony Bridge).
  • Extensibility: Customizable via configuration (e.g., asset paths, Gotenberg DSN, Chromium flags) and supports advanced features like headers/footers, PDF encryption, and webhooks—useful for complex document workflows.
  • Async Support: Webhook integration enables event-driven processing (e.g., long-running PDF generation), which can be adapted to Laravel’s queue systems (e.g., Horizon).

• Gaps:

  • Laravel Ecosystem Fit: Primarily designed for Symfony; requires adaptation for Laravel (e.g., service container binding, Twig integration via laravel-twig-bridge).
  • State Management: Laravel’s stateless middleware vs. Symfony’s request context may require adjustments for local asset resolution (e.g., gotenberg_asset() Twig function).
  • Testing Complexity: PHPUnit-focused testing utilities may need Laravel-specific mocking (e.g., Mockery or Pest).

Integration Feasibility

• High: The bundle’s core functionality (HTTP API calls to Gotenberg) is language-agnostic. Key challenges:
  1. Service Container: Bind Symfony services to Laravel’s container (e.g., GotenbergPdfInterface to a Laravel service provider).
  2. Twig Integration: Use laravel-twig-bridge to render Twig templates in Laravel, then pass HTML to the bundle’s builders.
  3. Asset Handling: Replace Symfony’s asset() with Laravel’s asset() helper or a custom resolver for the gotenberg_asset() Twig function.
  4. HTTP Client: Leverage Laravel’s HttpClient or Guzzle instead of Symfony’s HttpClient (adapt the bundle’s http_client config).
• Workarounds:
  • Abstract the bundle behind a Laravel facade/service to hide Symfony dependencies.
  • Use Laravel’s View system for HTML generation instead of Twig where possible.

Technical Risk

• Medium-High:
  • Dependency Conflicts: Symfony components (e.g., HttpClient, Twig) may conflict with Laravel’s versions. Mitigate via strict composer constraints or isolation (e.g., Docker).
  • Performance Overhead: Gotenberg runs as a separate service (Docker/container), adding latency (~100–300ms per request). Cache generated PDFs/screenshots aggressively (e.g., Laravel’s cache() or Redis).
  • Local Development: Debugging requires local Gotenberg setup (Docker) and proper SSL/configuration for self-signed certs (see FAQ).
  • Upgrade Risk: Tight coupling to Gotenberg’s API version (e.g., 8.x) may require bundle updates for new features (e.g., skipNetworkAlmostIdleEvent).

Key Questions

1. Use Case Priority:
   • Are PDFs/screenshots generated on-demand (e.g., user-triggered) or batch-processed (e.g., nightly reports)? This dictates caching strategy and async needs.
   • What’s the volume? High throughput may require Gotenberg scaling (e.g., Kubernetes) or Laravel queue batching.
2. Asset Dependencies:
   • How are static assets (images, CSS) managed? Will they be served via Laravel’s public folder or a CDN?
3. Error Handling:
   • How should failures (e.g., Gotenberg timeout, invalid HTML) be surfaced? (e.g., Laravel exceptions, user notifications).
4. Testing:
   • Should tests mock Gotenberg entirely or use a local instance? (Trade-off: realism vs. speed.)
5. Deployment:
   • Will Gotenberg run in the same container as Laravel, or separately? (Impacts networking, secrets management.)

Integration Approach

Stack Fit

• Laravel Compatibility:

  • Core: Replace Symfony’s HttpClient with Laravel’s HttpClient or Guzzle via a custom adapter.
  • Twig: Use laravel-twig-bridge to render Twig templates in Laravel. Modify the bundle’s gotenberg_asset() function to use Laravel’s asset() helper.
  • DI Container: Bind Symfony services to Laravel’s container in a service provider:

    $this->app->bind(GotenbergPdfInterface::class, function ($app) {
        return new GotenbergPdf($app->make(HttpClient::class), $app->get('config')['gotenberg']);
    });
    

  • Routing: Use Laravel’s route model binding or middleware to inject GotenbergPdfInterface into controllers.

• Gotenberg Setup:

  • Deploy Gotenberg as a Docker container (recommended) or Kubernetes pod, with Laravel accessing it via HTTP.
  • Configure Laravel’s .env with:

    GOTENBERG_DSN=http://gotenberg:3000
    GOTENBERG_CHROMIUM_FLAGS="--disable-gpu --no-sandbox"
    

  • For local dev, use host.docker.internal to avoid SSL issues (see FAQ).

Migration Path

1. Phase 1: Proof of Concept (1–2 weeks)

   • Set up Gotenberg locally and test basic PDF/screenshot generation from URLs.
   • Adapt a single Laravel controller to use the bundle via a facade/service.
   • Validate Twig integration with laravel-twig-bridge.

2. Phase 2: Core Integration (2–3 weeks)

   • Replace Symfony’s HttpClient with Laravel’s equivalent.
   • Implement asset resolution for gotenberg_asset().
   • Add caching (e.g., Cache::remember) for generated outputs.
   • Write unit tests for critical paths (e.g., PDF generation from HTML).

3. Phase 3: Advanced Features (1–2 weeks)

   • Implement async processing via Laravel queues + Gotenberg webhooks.
   • Add support for headers/footers, PDF encryption, or LibreOffice conversions as needed.
   • Optimize Gotenberg resource usage (e.g., connection pooling).

4. Phase 4: Deployment (1 week)

   • Containerize Gotenberg and Laravel (or deploy separately).
   • Set up monitoring (e.g., Prometheus for Gotenberg, Laravel Horizon for queues).
   • Document failure modes (e.g., Gotenberg OOM, network issues).

Compatibility

• Laravel Versions: Tested with Symfony 6.4/8.2; Laravel 10+ should work with minor adjustments (e.g., container binding syntax).
• Gotenberg Versions: Bundle supports Gotenberg 8.x. Ensure your deployment matches (e.g., gotenberg/gotenberg:8).
• PHP Extensions: Requires cURL, DOM, and GD (for image handling). Verify via php -m.

Sequencing

1. Prerequisite: Deploy and test Gotenberg independently (e.g., via Docker Compose).
2. Order:
   • URL-based generation (simplest) → Twig/HTML → Office docs → Async/webhooks.
   • Start with stream() responses, then add file storage (e.g., generate()->save()).
3. Dependencies:
   • Twig integration must precede HTML-based builders.
   • Async features require queue setup (e.g., Laravel Horizon).

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor Gotenberg API changes (e.g., breaking changes in 8.x). The bundle abstracts most of this, but new features may require updates.
  • Dependency conflicts: Pin Symfony components to specific versions in composer.json to avoid Laravel conflicts.
• Configuration Drift:
  • Centralize Gotenberg settings in Laravel’s .env (e.g., GOTENBERG_DSN, CHROMIUM_FLAGS).
  • Use Laravel’s config caching (php artisan config:cache) to avoid runtime overrides.

Support

• Debugging:
  • Gotenberg Logs: Access container logs (docker logs gotenberg) for Chromium/LibreOffice errors.
  • Laravel Logs: Log Gotenberg API responses/errors (e.g., try-catch blocks around generate()).
  • Profiler: Use the bundle’s built-in profiler (if Twig is enabled) or Laravel’s debugbar.
• Common Issues:
  • Blank Output: Check SSL certs (add --ignore-certificate-errors to Chromium flags) and Gotenberg’s ability to reach Laravel’s URLs (use host.docker.internal in dev).
  • Timeouts: Increase Gotenberg’s `CHROMI