Gotenberg Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Microservice Integration: The package abstracts PDF generation via Gotenberg (a microservice for document conversion), aligning well with modern architectures where heavy processing (e.g., Chromium-based rendering) is offloaded to dedicated services.
• Symfony Ecosystem: Designed for Symfony, but leverages Laravel’s HTTP client and service container patterns via Sensiolabs/GotenbergBundle (dependency). Requires minimal adaptation for Laravel (e.g., replacing Symfony’s HttpClient with Laravel’s Http facade or Guzzle).
• Separation of Concerns: Encapsulates PDF generation logic, reducing clutter in application controllers/models. Ideal for use cases like invoicing, reporting, or dynamic document generation.

Integration Feasibility

• Low Coupling: The bundle’s core functionality (API calls to Gotenberg) is decoupled from Symfony-specific components, making it feasible for Laravel with:
  • HTTP Client Replacement: Laravel’s Http facade or Guzzle can replace Symfony’s HttpClient.
  • Service Container Binding: Laravel’s service container can bind the Gotenberg client similarly to Symfony’s scoped_clients.
• Configuration Overhead: Requires manual setup of routes and configuration (unlike auto-discoverable Laravel packages), but the YAML structure is straightforward to replicate in Laravel’s config/gotenberg.php.

Technical Risk

• Dependency on External Service: Gotenberg must be hosted (Docker, cloud, or self-managed), adding operational complexity. Risk mitigated by:
  • Using a managed service (e.g., Gotenberg Cloud).
  • Local Docker setup for development.
• Laravel-Specific Gaps:
  • Routing: Laravel’s routing system differs from Symfony’s. The routes.php file would need conversion to Laravel’s Route::post() syntax.
  • Event Dispatching: If the bundle uses Symfony events (e.g., for post-generation hooks), these would need replacement with Laravel’s Events system.
• Output Handling: The output_path config assumes filesystem storage. Laravel’s storage system (e.g., Storage::disk()) would require customization for cloud storage (S3, etc.).

Key Questions

1. Gotenberg Hosting:
   • Will Gotenberg run in-house (Docker) or via a third-party service? What are the latency/SLA requirements?
2. Laravel Adaptation Effort:
   • Is the team comfortable rewriting Symfony-specific components (routing, events) or preferring a pure Laravel alternative (e.g., spatie/pdf-to-text for simpler use cases)?
3. Scaling PDF Generation:
   • Will high-volume PDF generation require queueing (e.g., Laravel Queues + Gotenberg API rate limits)?
4. Security:
   • How will the GOTENBERG_DSN (e.g., http://gotenberg:3000) be secured (e.g., environment variables, VPC peering)?
5. Fallback Mechanism:
   • What’s the plan if Gotenberg is unavailable (e.g., fallback to a headless Chrome library like dompdf or wkhtmltopdf)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • HTTP Client: Replace Symfony’s HttpClient with Laravel’s Http facade or Guzzle. Example:

    // config/gotenberg.php
    'http_client' => [
        'base_uri' => env('GOTENBERG_DSN'),
        'timeout'  => 30,
    ],
    

  • Service Container: Bind the Gotenberg client as a singleton in AppServiceProvider:

    $this->app->singleton('gotenberg.client', function ($app) {
        return new \GuzzleHttp\Client([
            'base_uri' => config('gotenberg.http_client.base_uri'),
        ]);
    });
    

  • Routing: Convert Symfony’s routes.php to Laravel’s routes/web.php:

    Route::post('/api/gotenberg', [GotenbergController::class, 'generate'])->name('gotenberg.generate');
    

• Storage: Extend the output_path config to support Laravel’s storage system:

  'output_path' => 'pdfs', // Uses Laravel's storage disk
  

  Then use Storage::disk('local')->put() to save files.

Migration Path

1. Phase 1: Proof of Concept
   • Deploy Gotenberg via Docker locally.
   • Implement a minimal Laravel service to call Gotenberg’s API directly (bypassing the bundle) to validate functionality.
   • Example API call:

     $response = Http::post('http://gotenberg:3000/forms/chromium/convert/html', [
         'html' => '<h1>Test</h1>',
     ]);
     

2. Phase 2: Bundle Integration
   • Fork the bundle or create a Laravel wrapper to abstract Symfony dependencies.
   • Replace routing/event systems with Laravel equivalents.
3. Phase 3: Production Readiness
   • Containerize Gotenberg (Docker/Kubernetes) or use a managed service.
   • Implement retry logic for API failures (e.g., using Laravel’s retry helper).

Compatibility

• Gotenberg API: The bundle uses Gotenberg’s REST API, which is language-agnostic. Laravel’s HTTP client will work seamlessly.
• Configuration: The YAML configs can be translated to Laravel’s config/gotenberg.php with minimal changes.
• Dependencies: The bundle depends on sensiolabs/gotenberg-bundle (Symfony) and gotenberg/gotenberg (Docker image). Laravel projects will only need the latter.

Sequencing

1. Infrastructure Setup:
   • Deploy Gotenberg (Docker compose example below).

   # docker-compose.yml
   services:
     gotenberg:
       image: gotenberg/gotenberg:7
       ports:
         - "3000:3000"
       environment:
         - GOTENBERG__FONTS_DIRECTORY=/tmp/gotenberg/fonts
   

2. Laravel Configuration:
   • Add gotenberg config file.
   • Bind the HTTP client in AppServiceProvider.
3. Service Layer:
   • Create a GotenbergService class to handle PDF generation logic.
4. Routing/Controller:
   • Expose endpoints for PDF generation (e.g., POST /api/documents/pdf).
5. Testing:
   • Test locally with Docker, then migrate to production hosting.

Operational Impact

Maintenance

• Bundle Updates: The package is unmaintained (0 stars, no dependents). Plan for:
  • Forking and maintaining the bundle if critical bugs arise.
  • Monitoring Gotenberg’s GitHub for breaking changes.
• Dependency Management:
  • Pin gotenberg/gotenberg image version in Docker (e.g., 7).
  • Use Laravel’s composer.json to lock versions of indirect dependencies (e.g., Guzzle).

Support

• Debugging:
  • Gotenberg logs can be accessed via Docker logs (docker logs gotenberg).
  • Laravel’s Http client provides response debugging:

    $response = Http::debug()->post(...);
    dd($response->toArray());
    

• Community: Limited support due to the bundle’s obscurity. Rely on:
  • Gotenberg’s community.
  • Symfony-to-Laravel translation efforts (e.g., Stack Overflow).

Scaling

• Horizontal Scaling:
  • Gotenberg can be scaled independently (e.g., Kubernetes deployment with auto-scaling).
  • Laravel’s queue system can distribute PDF generation jobs (e.g., GeneratePdfJob).
• Performance:
  • API Latency: Gotenberg’s Chromium-based rendering is resource-intensive. Monitor CPU/memory usage in Docker.
  • Queue Throttling: Use Laravel’s afterCommit() to avoid long-running transactions during PDF generation.
• Rate Limiting: Gotenberg’s API may throttle requests. Implement exponential backoff in Laravel:

  use Symfony\Component\HttpClient\RetryableHttpClient;
  
  $client = new RetryableHttpClient(
      Http::client(),
      retry: [
          'max_retries' => 3,
          'delay' => 1000,
      ]
  );
  

Failure Modes