Pdflatex Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require cyberspectrum/pdflatex-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Cyberspectrum\PdfLaTeXBundle\PdfLaTeXBundle::class => ['all' => true],
   ];
   

2. Configuration Override default settings in config/packages/cyberspectrum_pdflatex.yaml:

   cyberspectrum_pdflatex:
       pdflatex_path: '/usr/local/texlive/2023/bin/x86_64-linux/pdflatex'  # Adjust path
       timeout: 30  # Seconds before failing
       log_file: '%kernel.logs_dir%/pdflatex.log'  # Optional log path
   

3. First Use Case Generate a PDF from a Twig template:

   use Cyberspectrum\PdfLaTeXBundle\Service\PdfLaTeXService;
   
   class MyController extends AbstractController {
       public function generatePdf(PdfLaTeXService $pdfLaTeXService) {
           $template = $this->renderView('path/to/your_template.tex.twig', [
               'title' => 'My Document',
               'content' => 'Hello, LaTeX!'
           ]);
   
           $pdf = $pdfLaTeXService->generate($template);
           return new Response($pdf, 200, ['Content-Type' => 'application/pdf']);
       }
   }
   

Implementation Patterns

Workflow: Twig-to-PDF Pipeline

1. Template Design Use Twig templates with .tex.twig extension (e.g., document.tex.twig). Example:

   \documentclass{article}
   \begin{document}
       \title{{ title }}
       \author{{ author }}
       \maketitle
       {{ content|raw }}
   \end{document}
   

2. Service Integration Inject PdfLaTeXService into controllers/services:

   public function generateReport(PdfLaTeXService $pdfLaTeX) {
       $data = $this->fetchReportData();
       $template = $this->renderView('reports/document.tex.twig', $data);
       return $pdfLaTeX->generate($template);
   }
   

3. Batch Processing Process multiple files in a loop:

   foreach ($templates as $templatePath) {
       $template = $this->renderView($templatePath, $data);
       $pdf = $pdfLaTeXService->generate($template);
       $this->storePdf($pdf, $templatePath);
   }
   

4. Error Handling Wrap calls in try-catch:

   try {
       $pdf = $pdfLaTeXService->generate($template);
   } catch (\RuntimeException $e) {
       $this->addFlash('error', 'PDF generation failed: ' . $e->getMessage());
       return $this->redirectToRoute('home');
   }
   

Gotchas and Tips

Pitfalls

1. Path Configuration

   • Issue: pdflatex_path may fail silently if incorrect.
   • Fix: Verify path exists and is executable:

     if (!file_exists($config['pdflatex_path'])) {
         throw new \RuntimeException('pdflatex not found at: ' . $config['pdflatex_path']);
     }
     

2. Timeouts

   • Complex documents may exceed timeout. Monitor logs (log_file) for hangs.

3. Twig Security

   • Risk: Raw LaTeX in Twig templates can expose command injection.
   • Mitigation: Whitelist safe variables or use |raw sparingly.

4. Dependency Conflicts

   • Ensure symfony/process (for exec) and twig are compatible with your Symfony version.

Debugging

• Logs: Check log_file for LaTeX errors (e.g., missing packages).
• Dry Runs: Test with simple templates first:

  \documentclass{article}
  \begin{document}
      Test PDF
  \end{document}
  

• Environment Checks:

  which pdflatex  # Verify path
  pdflatex --version  # Check LaTeX installation
  

Extension Points

1. Custom Commands Extend PdfLaTeXService to support other LaTeX commands (e.g., latexmk):

   // src/Service/CustomPdfService.php
   class CustomPdfService extends PdfLaTeXService {
       protected function getCommand(): string {
           return 'latexmk -pdf ' . escapeshellarg($this->getTempFile());
       }
   }
   

2. Pre/Post-Processing Hook into template rendering or PDF generation:

   // config/services.yaml
   services:
       App\EventListener\PdfListener:
           tags:
               - { name: kernel.event_listener, event: pdflatex.pre_generate, method: onPreGenerate }
   

3. Storage Integration Combine with oneup/flysystem-bundle for cloud storage:

   use Oneup\FlysystemBundle\FilesystemMap;
   
   public function storePdf(string $pdf, string $filename, FilesystemMap $filesystems) {
       $fs = $filesystems->get('s3');
       $fs->write('pdfs/' . $filename . '.pdf', $pdf);
   }
   

Performance Tips

• Cache Templates: Compile Twig templates to PHP for repeated use.
• Temp Files: Clean up temporary .tex files post-generation:

  $pdfLaTeXService->generate($template, true); // Auto-delete temp file