Pdf Generator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 2lenet/pdf-generator-bundle
   

   Add unoserver to your docker-compose.yml (required for Word-to-PDF conversion):

   unoserver:
     image: registry.2le.net/2le/2le:unoserver
   

2. Publish Configuration

   php artisan vendor:publish --provider="Lle\PdfGeneratorBundle\PdfGeneratorBundle" --tag="config"
   

   Update config/lle_pdf_generator.php with your template path (default: data/pdfmodel).

3. First Use Case Place a Word document (e.g., mydoc.doc) in data/pdfmodel/. Generate PDF via Twig:

   <a href="{{ path('lle_pdf_generator_show_ressource', {'id': 'mydoc'}) }}">Download PDF</a>
   

   The bundle auto-detects mydoc.doc and converts it to PDF using the word_to_pdf generator.

Implementation Patterns

Core Workflow

1. Template Management

   • Store Word/ODT templates in config('lle_pdf_generator.path').
   • Naming convention: template_name.doc → Generates template_name.pdf.
   • Example: invoice_template.doc → Accessible via id: 'invoice_template'.

2. Dynamic Generation

   • Via Route: Use the auto-generated route lle_pdf_generator_show_ressource with the template ID.
   • Via Service:

     use Lle\PdfGeneratorBundle\Service\PdfGeneratorService;
     
     $pdfGenerator = app(PdfGeneratorService::class);
     $pdfContent = $pdfGenerator->generate('template_name');
     return response($pdfContent)->header('Content-Type', 'application/pdf');
     

3. Custom Generators Override the default (word_to_pdf) by extending the PdfGeneratorInterface:

   namespace App\Service;
   
   use Lle\PdfGeneratorBundle\Service\PdfGeneratorInterface;
   
   class CustomPdfGenerator implements PdfGeneratorInterface {
       public function generate(string $templatePath): string {
           // Custom logic (e.g., HTML-to-PDF via Dompdf)
       }
   }
   

   Register in config/lle_pdf_generator.php:

   default_generator: "custom_generator"
   

4. Tagging System

   • List Tags: Add a route to lle_pdf_generator_admin_balise (e.g., via Crudit):

     public function getListActions(): array {
         return [
             ListAction::new(
                 "Tags",
                 Path::new('lle_pdf_generator_admin_balise'),
                 Icon::new("tag")
             ),
         ];
     }
     

   • Define Tags: Use pdf_generator.yaml (project-specific):

     templates:
       invoice:
         tags: ["finance", "report"]
       contract:
         tags: ["legal"]
     

5. Integration with CRUD

   • Attach PDF generation to entity actions:

     public function getListActions(): array {
         $actions = parent::getListActions();
         $actions[] = ListAction::new(
             "Generate PDF",
             Path::new('lle_pdf_generator_show_ressource', ['id' => 'contract']),
             Icon::new("file-pdf")
         );
         return $actions;
     }
     

Gotchas and Tips

Pitfalls

1. Unoserver Dependency

   • Issue: word_to_pdf generator fails if unoserver is unreachable.
   • Fix: Ensure unoserver is running in Docker and accessible via the configured host/port (default: http://unoserver:3000).

2. Template Path Resolution

   • Issue: Missing templates throw FileNotFoundException.
   • Fix: Verify lle_pdf_generator.path points to an accessible directory and templates exist with .doc/.odt extensions.

3. Caching Headaches

   • Issue: Generated PDFs may not reflect template changes.
   • Fix: Clear cache after updating templates:

     php artisan cache:clear
     php artisan config:clear
     

4. Route Conflicts

   • Issue: lle_pdf_generator_show_ressource may clash with existing routes.
   • Fix: Override the route in config/routes.yaml:

     lle_pdf_generator:
       resource: "@LlePdfGeneratorBundle/Resources/config/routes.yaml"
       prefix: "/pdf"
     

Debugging Tips

1. Log Generator Output Enable debug mode in config/lle_pdf_generator.php:

   debug: true
   

   Logs generator calls and errors to storage/logs/laravel.log.

2. Validate Template IDs Use the PdfGeneratorService to check if a template exists:

   if (!$pdfGenerator->templateExists('nonexistent')) {
       // Handle error
   }
   

3. Test Generators Locally Mock unoserver for local testing:

   # docker-compose.yml
   unoserver:
     image: registry.2le.net/2le/2le:unoserver
     ports:
       - "3000:3000"
   

   Access via http://localhost:3000 (if using Docker’s host network).

Extension Points

1. Custom Generators

   • Implement PdfGeneratorInterface for new formats (e.g., HTML-to-PDF):

     class DompdfGenerator implements PdfGeneratorInterface {
         public function generate(string $templatePath): string {
             $html = file_get_contents($templatePath . '.html');
             $dompdf = new \Dompdf\Dompdf();
             $dompdf->loadHtml($html);
             $dompdf->render();
             return $dompdf->output();
         }
     }
     

2. Pre/Post-Processing

   • Extend PdfModel entity to add metadata or hooks:

     namespace App\Entity;
     
     use Lle\PdfGeneratorBundle\Entity\PdfModel as BasePdfModel;
     
     class PdfModel extends BasePdfModel {
         public function getCustomData(): array {
             return ['author' => 'App'];
         }
     }
     

3. Tag-Based Routing

   • Filter templates by tags in your admin panel:

     $taggedTemplates = $pdfGenerator->getTemplatesByTag('finance');
     

4. Queue PDF Generation

   • Offload heavy conversions to a queue (e.g., Laravel Queues):

     dispatch(new GeneratePdfJob('template_name', $user->email));
     

     Implement the job to use PdfGeneratorService.