Getting Started

Minimal Steps

Installation:
```
composer require bideogemu/mpdf-bundle
```
Ensure BideoGemu\MpdfBundle\BideoGemuMpdfBundle::class is enabled in config/bundles.php.

First Use Case: Generate a PDF in a Laravel controller:

use BideoGemu\MpdfBundle\Factory\MpdfFactory;

public function generatePdf(MpdfFactory $mpdfFactory) {
    $mpdf = $mpdfFactory->createMpdfObject([
        'mode' => 'utf-8',
        'format' => 'A4',
    ]);

    $mpdf->WriteHTML($this->renderView('pdf.template.twig', ['data' => $data]));
    return $mpdfFactory->createDownloadResponse($mpdf, 'document.pdf');
}

Key Files to Review:
- config/packages/bideogemu_mpdf.yaml (default config).
- vendor/bideogemu/mpdf-bundle/src/Factory/MpdfFactory.php (factory logic).
- Example Twig templates (e.g., resources/views/pdf/template.twig).

Implementation Patterns

Usage Patterns

Factory-Based Instantiation: Always use MpdfFactory to create MPDF instances. Avoid direct instantiation of \Mpdf\Mpdf:
```
// Good
$mpdf = $mpdfFactory->createMpdfObject($customOptions);

// Avoid
$mpdf = new \Mpdf\Mpdf($options);
```

Configuration Management:

Default Options: Define in config/packages/bideogemu_mpdf.yaml:

bideogemu_mpdf:
    default_options:
        mode: utf-8
        format: A4
        margin_header: 5
        margin_footer: 5

Runtime Overrides: Merge with defaults via the factory:

$mpdf = $mpdfFactory->createMpdfObject([
    'orientation' => 'L', // Overrides default
]);

Twig Integration:

Render Twig templates to HTML before passing to MPDF:

$html = $this->renderView('pdf.template.twig', ['data' => $data]);
$mpdf->WriteHTML($html);

Use partials for headers/footers:

$mpdf->SetHTMLHeader($this->renderView('pdf.header.twig'));

Response Handling:

Download: Force download with:

return $mpdfFactory->createDownloadResponse($mpdf, 'filename.pdf');

Inline Display: Stream directly:

return $mpdfFactory->createStreamResponse($mpdf, 'filename.pdf');

Queueing for Large PDFs: Use Laravel queues to avoid timeouts:

GeneratePdfJob::dispatch($data)->onQueue('pdfs');

Job example:

public function handle() {
    $mpdf = $this->mpdfFactory->createMpdfObject([]);
    $mpdf->WriteHTML($this->renderView('pdf.template.twig', ['data' => $this->data]));
    Storage::put('pdfs/temp.pdf', $mpdf->Output('', 'S'));
}

Workflows

Dynamic PDF Generation:

Fetch data from a model, pass to Twig, and generate PDF in one flow:

public function generateInvoice($invoiceId) {
    $invoice = Invoice::findOrFail($invoiceId);
    $mpdf = $this->mpdfFactory->createMpdfObject(['format' => 'A4']);
    $mpdf->WriteHTML($this->renderView('invoices/pdf.twig', ['invoice' => $invoice]));
    return $this->mpdfFactory->createDownloadResponse($mpdf, "invoice_{$invoiceId}.pdf");
}

Reusable PDF Components:

Create base Twig templates with blocks for headers/footers:

{# resources/views/pdf/base.twig #}
<!DOCTYPE html>
<html>
    <head>
        {% block head %}{% endblock %}
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
</html>

Extend for specific PDFs:

{# resources/views/pdf/report.twig #}
{% extends 'pdf/base.twig' %}
{% block content %}
    {{ include('pdf/report_content.twig') }}
{% endblock %}

Testing:

Mock MpdfFactory in tests:

$mockMpdf = Mockery::mock(\Mpdf::class);
$mockMpdf->shouldReceive('WriteHTML')->once();
$mockMpdf->shouldReceive('Output')->once()->andReturn('PDF_CONTENT');

$factory = $this->app->make(MpdfFactory::class);
$factory->shouldReceive('createMpdfObject')->andReturn($mockMpdf);

Integration Tips

Laravel Service Provider: Bind the factory explicitly if autowiring fails:

public function register() {
    $this->app->bind(MpdfFactory::class, function ($app) {
        return new MpdfFactory(
            $app['config']['mpdf.default_options'],
            storage_path('app/mpdf_cache')
        );
    });
}

Custom MPDF Extensions: Extend the factory to support custom MPDF classes:

class CustomMpdfFactory extends MpdfFactory {
    protected function createMpdfInstance(array $options) {
        return new CustomMpdf($options);
    }
}

'mpdf_factory' => \App\Services\CustomMpdfFactory::class,

Environment-Specific Configs: Override defaults per environment:

# config/packages/bideogemu_mpdf.yaml
when@dev:
    default_options:
        format: Letter

Caching: Cache compiled Twig templates for PDFs:

$twig = $this->app->make(Twig::class);
$twig->getLoader()->setCache($this->app['path.cache'].'/twig');

Gotchas and Tips

Pitfalls

Configuration Merging:

Issue: Runtime options may silently override defaults without warning.

Fix: Explicitly log merged options:

$options = array_merge($this->defaultOptions, $runtimeOptions);
$this->logger->debug('MPDF options merged:', ['options' => $options]);

Cache Directory Permissions:
- Issue: MPDF fails silently if cache_dir is unwritable.
- Fix: Set permissions and validate:
```
$cacheDir = storage_path('app/mpdf_cache');
if (!is_writable($cacheDir)) {
    mkdir($cacheDir, 0755, true);
}
```
Twig Autoloader Conflicts:
- Issue: Twig templates may fail to load if the autoloader isn’t configured.
- Fix: Ensure Twig is properly set up in Laravel:
```
$this->app->register(TwigServiceProvider::class);
```
Deprecated DI Arguments:
- Issue: Older code may pass non-typed arguments to MpdfFactory.
- Fix: Update constructor calls to use typed hints:
```
// Old (may fail in v2.7+)
new MpdfFactory($options);

// New
new MpdfFactory($defaultOptions, $cacheDir);
```
Memory Limits:
- Issue: Large PDFs may hit PHP’s memory_limit.
- Fix: Increase limit or optimize templates:
```
ini_set('memory_limit', '512M');
```

Debugging

Enable MPDF Debugging: Add to config/packages/bideogemu_mpdf.yaml:
```
debug: true
```
Logs errors to storage/logs/mpdf.log.
Check Output:
- Issue: Blank PDFs often mean HTML rendering failed.
- Debug: Output raw HTML to a file:
```
file_put_contents('debug.html', $htmlContent);
```
Symfony DI Errors:
- Issue: ParameterNotFoundException for missing config.
- Fix: Validate config/packages/bideogemu_mpdf.yaml exists and is loaded.
Twig Errors:
- Issue: Undefined variables in Twig templates.
- Fix: Use {{ dump(data) }} in templates to debug variables.

Tips

Default Options:
- Centralize common options in config to avoid repetition:

Mpdf Bundle Laravel Package