Doc Img Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aldaflux/doc-img-bundle
   

   Ensure your composer.json meets the package’s PHP/Symfony version requirements (PHP ≥5.3.2, Symfony ≥3.0).

2. Bundle Registration Add to config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 3):

   return [
       // ...
       Aldaflux\DocImgBundle\AldafluxDocImgBundle::class => ['all' => true],
   ];
   

3. Configuration Define the web_dir in config/packages/aldaflux_doc_img.yaml:

   aldaflux_doc_img:
       web_dir: "%kernel.project_dir%/public"
   

4. First Use Case Render a Twig template with embedded images (use double quotes for src attributes):

   <img src="/bundles/aldafluxdocimg/images/inda.png">
   <img src="https://upload.wikimedia.org/.../Logo_Microsoft_Word_2013.png">
   

   Generate an MHT file in a controller:

   use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
   use Symfony\Component\HttpFoundation\Response;
   
   class DocController extends AbstractController {
       public function generateDoc() {
           $html = $this->renderView('path/to/your_template.html.twig');
           $mht = $this->get('HtmlToMht')->GenereHtmlToMht($html);
   
           $response = new Response($mht, 200, [
               'Content-Type' => 'application/vnd.ms-word',
               'Content-Disposition' => 'attachment; filename="document.doc"',
           ]);
           return $response;
       }
   }
   

Implementation Patterns

Workflow: Dynamic Document Generation

1. Template Design

   • Use Twig templates with embedded images (local or remote). Remote images must be publicly accessible.
   • Example: templates/documents/invoice.html.twig with dynamic data:

     <h1>{{ customer.name }}</h1>
     <img src="{{ asset('images/logo.png') }}">
     

2. Controller Integration

   • Pass dynamic data to the template:

     $html = $this->renderView('documents/invoice.html.twig', [
         'customer' => $customerData,
     ]);
     

   • Generate and return the MHT file:

     $mht = $this->get('HtmlToMht')->GenereHtmlToMht($html);
     return new Response($mht, 200, [
         'Content-Disposition' => 'attachment; filename="invoice.doc"',
     ]);
     

3. Routing

   • Expose the endpoint via annotations (Symfony 3) or YAML (Symfony 4):

     # config/routes.yaml
     app.doc_generate:
         path: /generate-doc
         controller: App\Controller\DocController::generateDoc
     

4. Local Image Handling

   • Place images in public/bundles/aldafluxdocimg/images/ or use Symfony’s asset() helper:

     <img src="{{ asset('bundles/aldafluxdocimg/images/logo.png') }}">
     

Advanced Patterns

• Batch Processing Loop through records and generate multiple MHT files:

  foreach ($invoices as $invoice) {
      $html = $this->renderView('documents/invoice.html.twig', ['invoice' => $invoice]);
      $mht = $this->get('HtmlToMht')->GenereHtmlToMht($html);
      $this->saveMhtToDisk($mht, "invoice_{$invoice->id}.doc");
  }
  

• Custom Image Paths Override the web_dir per environment (e.g., config/packages/dev/aldaflux_doc_img.yaml):

  aldaflux_doc_img:
      web_dir: "%kernel.project_dir%/public/dev-assets"
  

• Testing Use the built-in test route (/aldaflux/) to verify functionality:

  php bin/console server:run
  

  Visit http://localhost:8000/aldaflux/ to test the bundle’s default template.

Gotchas and Tips

Pitfalls

1. Image Paths

   • Local Images: Must be in public/bundles/aldafluxdocimg/images/ or referenced via asset().
   • Remote Images: Must be publicly accessible (no auth/HTTPS issues). Test URLs in a browser first.
   • Double Quotes: Single quotes (') in src attributes break the MHT generation. Use ".

2. Symfony Version Mismatch

   • The bundle requires Symfony ≥3.0. If using Symfony 4/5, ensure config/bundles.php is updated.
   • Error: Class 'Aldaflux\DocImgBundle\AldafluxDocImgBundle' not found → Verify bundle registration.

3. MHT Output Issues

   • Corrupted Files: If the MHT file opens as gibberish, check for:
     • Invalid HTML (use browser dev tools to validate).
     • Unescaped characters in dynamic content (use Twig’s |e filter if needed).
   • Missing Images: Ensure web_dir points to the correct public directory.

4. Caching

   • MHT files are not cached by default. For large-scale generation, implement a cache layer (e.g., Redis) to store generated files.

Debugging Tips

1. Log HTML Before Conversion Dump the Twig-rendered HTML to debug:

   file_put_contents('debug.html', $html);
   

   Open debug.html in a browser to verify rendering.

2. Check MHT Generation Save the raw MHT output for inspection:

   file_put_contents('debug.mht', $mht);
   

   Open debug.mht in Word to diagnose issues.

3. Service Not Found If $this->get('HtmlToMht') fails:

   • Verify the service is autowired (check services.yaml for overrides).
   • Clear the cache:

     php bin/console cache:clear
     

Extension Points

1. Custom MHT Headers Extend the Response headers for metadata (e.g., author, subject):

   $response->headers->set('X-Author', 'Your Name');
   $response->headers->set('Subject', 'Generated Document');
   

2. Post-Processing Hook into the MHT generation to modify content (e.g., add watermarks):

   $mht = $this->get('HtmlToMht')->GenereHtmlToMht($html);
   $mht = str_replace('<body>', '<body><div class="watermark">Draft</div>', $mht);
   

3. Image Optimization Pre-process images (resize/compress) before embedding them in the template:

   <img src="{{ asset('images/optimized_' ~ image.name) }}">
   

   Use libraries like intervention/image for dynamic resizing.

4. Event Listeners Listen for MHT generation events (if the bundle exposes them) to add custom logic:

   # config/services.yaml
   services:
       App\EventListener\DocGenerationListener:
           tags:
               - { name: kernel.event_listener, event: aldaflux.doc_img.generate, method: onGenerate }