Html Converter Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require bicpi/html-converter-bundle
   

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Bicpi\HtmlConverterBundle\BicpiHtmlConverterBundle::class => ['all' => true],
   ];
   

3. First Use Case Convert HTML to plain text in a controller:

   use Bicpi\HtmlConverterBundle\Converter\HtmlConverter;
   
   class MyController extends AbstractController
   {
       public function convertAction(HtmlConverter $converter)
       {
           $html = '<h1>Hello</h1><p>World!</p>';
           $text = $converter->convert($html);
           // Returns: "Hello\n\nWorld!"
           return new Response($text);
       }
   }
   

Key Files

• Configuration: config/packages/bicpi_html_converter.yaml (if present).
• Documentation: Resources/doc/index.md (for advanced usage).

Implementation Patterns

Common Workflows

1. Service Injection Use dependency injection for reusable conversions:

   public function __construct(private HtmlConverter $converter) {}
   
   public function processEmail(string $htmlBody): string
   {
       return $this->converter->convert($htmlBody);
   }
   

2. Twig Integration Add a Twig extension for frontend conversions:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension
   {
       public function __construct(private HtmlConverter $converter) {}
   
       public function getFunctions(): array
       {
           return [
               new \Twig\TwigFunction('html_to_text', [$this, 'convertHtml']),
           ];
       }
   
       public function convertHtml(string $html): string
       {
           return $this->converter->convert($html);
       }
   }
   

3. Batch Processing Loop through HTML strings (e.g., emails or CMS content):

   $converter = $container->get(HtmlConverter::class);
   $texts = array_map([$converter, 'convert'], $htmlArray);
   

Integration Tips

• Symfony Forms: Use for sanitizing user-submitted HTML before storage.
• API Responses: Convert rich-text fields to plain text for email notifications.
• Caching: Cache converted results if the same HTML is processed repeatedly.

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2016; verify compatibility with Symfony 5/6/7.
   • Check for forks (e.g., this one) if issues arise.

2. Configuration Overrides

   • The bundle may not support modern Symfony config formats (e.g., services.yaml overrides).
   • Default settings are hardcoded; inspect src/DependencyInjection/BicpiHtmlConverterExtension.php for options.

3. Edge Cases

   • Tables: The converter may flatten tables unpredictably. Workaround: Pre-process HTML with DOMDocument for critical cases.
   • Unicode: Non-Latin scripts (e.g., CJK) might render as ????. Tip: Test with your target locale early.

Debugging

• Log Raw Output Compare input/output to debug conversions:

  $converter->convert($html, ['debug' => true]); // If supported
  

• Fallback Logic Wrap conversions in a try-catch for graceful degradation:

  try {
      return $converter->convert($html);
  } catch (\Exception $e) {
      return fallbackToPlainText($html);
  }
  

Extension Points

1. Custom Rules Extend the underlying HtmlConverter library (if source is available) to add:

   • Preserved formatting (e.g., keep bold/italics as *text*).
   • Custom tag handling (e.g., <code> blocks).

2. Event Listeners Hook into Symfony events (e.g., kernel.response) to auto-convert HTML in responses:

   // src/EventListener/HtmlConverterListener.php
   class HtmlConverterListener
   {
       public function __construct(private HtmlConverter $converter) {}
   
       public function onKernelResponse(GetResponseEvent $event)
       {
           $response = $event->getResponse();
           if ($response->headers->contains('Content-Type', 'text/html')) {
               $body = $this->converter->convert($response->getContent());
               $response->setContent($body);
           }
       }
   }
   

3. Alternative Libraries If the bundle is limiting, consider:

   • symfony/panther for browser-based conversion.
   • paragonie/halite for cryptographic text extraction.