Mpdf Bundle Laravel Package

Getting Started

Prerequisites:

• PHP 8.2+ (required for Symfony 7 compatibility).
• Laravel 10+ (recommended, as it aligns with Symfony 7’s ecosystem).

Installation:

composer require bideogemu/mpdf-bundle

First Use Case:

1. Publish the bundle’s configuration:

   php artisan vendor:publish --provider="BideoGemu\MpdfBundle\MpdfBundle" --tag="config"
   

2. Configure config/mpdf.php with your desired defaults (e.g., cache_dir, default_options).
3. Inject the Mpdf service into a controller/service:

   use Mpdf\Mpdf;
   
   public function generatePdf(Mpdf $mpdf) {
       $mpdf->writeHTML('<h1>Hello, Symfony 7!</h1>');
       return $mpdf->output();
   }
   

   Note: The MpdfFactory now requires typed constructor arguments ($cacheDir, $defaultOptions), but these are auto-injected via Symfony’s DI container.

Implementation Patterns

1. Configuration Management:

• Use the Configuration.php tree to define hierarchical bundle options (e.g., nested default_options under mpdf).
• Override defaults in config/mpdf.php:

  return [
      'cache_dir' => storage_path('app/mpdf_cache'),
      'default_options' => [
          'mode' => 'utf-8',
          'format' => 'A4',
      ],
  ];
  

• Runtime options merge automatically with defaults via MpdfFactory.

2. Dependency Injection:

• Autowiring: Services like Mpdf and MpdfFactory are auto-wired. No manual binding needed.
• Explicit Injection: For custom factories or services, use typed hints:

  public function __construct(
      private string $cacheDir,
      private array $defaultOptions,
      private MpdfFactory $factory
  ) {}
  

3. Bundle Integration:

• Register the bundle in config/bundles.php (Symfony 7 style):

  return [
      BideoGemu\MpdfBundle\MpdfBundle::class => ['all' => true],
  ];
  

• For Laravel, the bundle auto-detects the environment (no manual registration required).

4. PDF Generation Workflow:

// Controller/Service
public function generateInvoice(Mpdf $mpdf, array $customOptions) {
    $mpdf->setOptions(array_merge($this->defaultOptions, $customOptions));
    $mpdf->WriteHTML($this->renderInvoiceView());
    return $mpdf->output('invoice.pdf', 'S'); // 'S' = send as attachment
}

Gotchas and Tips

Breaking Changes:

1. PHP 8.2+ Required: Downgrading will break autoloading and typed DI.
2. Constructor Arguments: MpdfFactory now requires $cacheDir and $defaultOptions. If not provided, the bundle throws a ParameterNotFoundException.
   • Fix: Ensure config/mpdf.php is published and populated.
3. Symfony 7 Bundle Structure: The bundles.php format is stricter. Laravel users may ignore this if the bundle auto-registers.

Debugging Tips:

• Missing Config: If Mpdf throws InvalidArgumentException, verify cache_dir is writable and default_options is an array.
• DI Errors: Use php artisan debug:container to inspect service wiring.
• Option Merging: Runtime options override defaults. Debug with:

  $mpdf->getOptions(); // Inspect merged config
  

Extension Points:

1. Custom Factories: Extend MpdfFactory to add pre-processing:

   class CustomMpdfFactory extends MpdfFactory {
       public function createCustomMpdf(): Mpdf {
           $mpdf = parent::createMpdf();
           $mpdf->setCompression(true);
           return $mpdf;
       }
   }
   

   Register it in services.yaml:

   services:
       App\Services\CustomMpdfFactory: ~
       Mpdf\Mpdf: '@App\Services\CustomMpdfFactory'
   

2. Event Listeners: Hook into Symfony’s kernel.request to modify Mpdf instances globally.

Performance:

• Cache Directory: Set cache_dir to a dedicated storage path (e.g., storage_path('app/mpdf_cache')) to avoid permission issues.
• Memory Limits: Large PDFs may hit PHP’s memory_limit. Increase it in .env:

  MEMORY_LIMIT=1G
  

Laravel-Specific Notes:

• The bundle leverages Laravel’s service container under the hood. No Symfony-specific config is required.
• For Blade templates, use @include('pdf.template') with ob_start()/ob_get_clean() to capture HTML before passing to Mpdf.

$html = \Illuminate\Support\Facades\View::make('pdf.invoice')->render();
$mpdf->WriteHTML($html);