Getting Started

Minimal Steps

Installation Run composer require borsaco/tcpdf-bundle in your Symfony project. Ensure your Symfony version is compatible (last release was 2019, so test thoroughly if using newer versions).
Enable the Bundle Add new Borsaco\TCPDFBundle\TCPDFBundle() to registerBundles() in AppKernel.php (or Kernel.php for Symfony 4+).

First Use Case: Generate a Basic PDF Inject the tcpdf service and create a PDF object:

use Symfony\Component\DependencyInjection\ContainerInterface;

public function generatePdf(ContainerInterface $container)
{
    $pdf = $container->get('tcpdf')->create();
    $pdf->AddPage();
    $pdf->SetFont('helvetica', 'B', 12);
    $pdf->Cell(0, 10, 'Hello, TCPDF in Symfony!', 0, 1, 'C');
    return $pdf->Output('example.pdf', 'I'); // 'I' forces download
}

Where to Look First
- Service Configuration: Check config/packages/tcpdf.yaml (auto-generated) for customization options.
- TCPDF Documentation: Refer to tcpdf.org/examples for advanced usage (e.g., tables, images, headers/footers).
- Bundle Source: Review Borsaco\TCPDFBundle\DependencyInjection\TCPDFExtension.php for configuration logic.

Implementation Patterns

Core Workflows

PDF Generation in Controllers Use dependency injection for the tcpdf service:

public function generateReportPdf(TCPDFService $tcpdfService)
{
    $pdf = $tcpdfService->create();
    // Customize PDF (AddPage, SetFont, Cell, etc.)
    return $pdf->Output('report.pdf', 'D'); // 'D' downloads file
}

Tip: Register the service as a controller argument in Symfony 4+ via services.yaml:

services:
    App\Controller\ReportController:
        arguments:
            $tcpdfService: '@tcpdf'

Reusable PDF Classes Extend TCPDF in a custom class (e.g., src/Service/CustomTCPDF.php):

namespace App\Service;

use TCPDF;

class CustomTCPDF extends TCPDF
{
    public function addCompanyHeader()
    {
        $this->SetFont('helvetica', 'B', 12);
        $this->Cell(0, 10, 'My Company', 0, 1, 'C');
    }
}

Configure the bundle to use it in config/packages/tcpdf.yaml:

tcpdf:
    class: 'App\Service\CustomTCPDF'

Streaming PDFs to Browser Use Output() with 'I' (inline) to display PDFs directly:
```
$pdf->Output('invoice.pdf', 'I');
```
For large files, stream chunks to avoid memory issues:
```
$pdf->Output('large_report.pdf', 'S'); // 'S' sends raw bytes
```

Dynamic Content Injection Pass data to templates (e.g., Twig) and merge it into PDFs:

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

Integration Tips

Twig Integration: Use tcpdf.writeHTML() with Twig-rendered strings for dynamic content.
Queueing Long-Generating PDFs: Offload PDF generation to a Symfony Messenger or queue system (e.g., Symfony Messenger + Doctrine Messenger).
Storage: Save PDFs to disk or cloud storage (e.g., AWS S3) using Symfony’s Filesystem or Flysystem:
```
$pdf->Output('path/to/file.pdf', 'F'); // 'F' saves to file
```

Testing: Mock the tcpdf service in PHPUnit:

$this->container->get('tcpdf')->expects($this->once())->method('create')->willReturn($mockPdf);

Gotchas and Tips

Pitfalls

Memory Limits
- TCPDF can consume significant memory for large PDFs. Use Output('S') for streaming or optimize content (e.g., compress images).
- Fix: Increase PHP memory limit (memory_limit in php.ini) or split PDF generation into chunks.
Deprecated Symfony Versions
- The bundle was last updated in 2019 and may not support Symfony 5/6+. Test thoroughly or fork the bundle.
- Workaround: Use a standalone TCPDF installation with Symfony’s ServiceLocator or a modern wrapper like spatie/pdf.

Configuration Overrides

Custom classes must extend TCPDF. The bundle throws an exception if invalid:

// Throws: "Class must extend TCPDF"
tcpdf:
    class: 'App\Service\InvalidClass'

Tip: Validate the class extends TCPDF programmatically:

if (!is_a($customClass, TCPDF::class, true)) {
    throw new \RuntimeException('Custom class must extend TCPDF');
}

Font Paths
- TCPDF requires font files (e.g., helvetica.ttf). Ensure they are accessible or configure custom paths:
```
tcpdf:
    font_paths: ['%kernel.project_dir%/vendor/tcpdf/fonts']
```

Service Container Access

Avoid direct container access in modern Symfony (Symfony 4+). Prefer constructor injection or autowiring:

// Bad (direct container access)
$pdf = $this->container->get('tcpdf')->create();

// Good (autowired service)
public function __construct(private TCPDFService $tcpdfService) {}

Debugging Tips

Check TCPDF Errors Enable TCPDF error reporting:

$pdf = $tcpdfService->create();
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->ErrorMode = 'return'; // Return errors as strings instead of throwing exceptions

Log PDF Generation Issues Wrap PDF generation in a try-catch block:

try {
    $pdf->Output('file.pdf', 'F');
} catch (\Exception $e) {
    $this->logger->error('PDF generation failed: ' . $e->getMessage());
    throw $e;
}

Verify Output
- Use 'D' (download) for debugging to inspect the generated PDF locally.
- Check TCPDF’s buffer for warnings:
```
$pdf->lastError(); // Returns the last error message
```

Extension Points

Custom Commands Create a Symfony command to generate PDFs in bulk:

namespace App\Command;

use Borsaco\TCPDFBundle\Service\TCPDFService;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class GeneratePdfCommand extends Command
{
    protected static $defaultName = 'app:generate-pdf';

    public function __construct(private TCPDFService $tcpdfService) {}

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $pdf = $this->tcpdfService->create();
        // Generate PDF logic
        $pdf->Output('command.pdf', 'D');
        return Command::SUCCESS;
    }
}

Event Listeners Trigger PDF generation on entity events (e.g., post-save):

namespace App\EventListener;

use App\Entity\Order;
use Borsaco\TCPDFBundle\Service\TCPDFService;
use Doctrine\ORM\Event\LifecycleEventArgs;

class OrderPdfListener
{
    public function __construct(private TCPDFService $tcpdfService) {}

    public function postPersist(Order $order, LifecycleEventArgs $args)
    {
        $pdf = $this->tcpdfService->create();
        // Generate PDF for $order
        $pdf->Output("order_{$order->getId()}.pdf", 'F');
    }
}

Twig Extensions Create a Twig extension to generate PDFs from templates:

namespace App\Twig;

use Borsaco\TCPDFBundle\Service\TCPDFService;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class PdfExtension extends AbstractExtension
{
    public function __construct(private TCPDFService $tcpdfService) {}

    public function getFunctions(): array
    {
        return [
            new TwigFunction('generate_p

Tcpdf Bundle Laravel Package