Commonmark Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avensome/commonmark-bundle
   

   Register the bundle in config/bundles.php:

   Avensome\CommonMarkBundle\AvensomeCommonMarkBundle::class => ['all' => true],
   

2. First Use Case: Convert a Markdown string to HTML in Twig:

   {{ '# Hello, CommonMark!' | markdown }}
   

   Or in a service:

   use League\CommonMark\CommonMarkConverter;
   
   class MyService {
       public function __construct(private CommonMarkConverter $converter) {}
   
       public function render(string $markdown): string {
           return $this->converter->convertToHtml($markdown);
       }
   }
   

3. Verify Configuration: Check config/packages/avensome_commonmark.yaml (auto-generated). Defaults are safe but can be overridden:

   avensome_commonmark:
       html_input: allow  # Allows HTML in Markdown input
   

Implementation Patterns

Common Workflows

1. Twig Integration:

   • Use the markdown filter for inline conversion:

     {{ article.content | markdown }}
     

   • Use the {% markdown %} tag for multi-line blocks (avoids escaping issues).

2. Service-Based Conversion:

   • Inject CommonMarkConverter into controllers/services for programmatic use:

     $html = $converter->convertToHtml($markdown);
     

   • Chain with other services (e.g., caching, sanitization):

     $html = $sanitizer->sanitize($converter->convertToHtml($markdown));
     

3. Dynamic Configuration:

   • Override settings per environment or per request:

     # config/packages/dev/avensome_commonmark.yaml
     avensome_commonmark:
         allow_unsafe_links: true  # Only in dev
     

   • Or dynamically in code:

     $converter = $container->get('avensome_commonmark.converter');
     $converter->getEnvironment()->addExtension(new MyExtension());
     

4. Extensions:

   • Enable extensions via services.yaml:

     services:
         My\CommonMark\Extension:
             tags:
                 - { name: avensome_commonmark.extension }
     

   • Example: Add tables with webuni/table-extension.

5. API Responses:

   • Convert Markdown to HTML for API responses:

     return new JsonResponse([
         'content' => $converter->convertToHtml($request->get('markdown'))
     ]);
     

Integration Tips

• Symfony Forms: Use with Symfony\Component\Form\Extension\Core\Type\TextareaType for Markdown input:

  $builder->add('description', TextareaType::class, [
      'attr' => ['class' => 'markdown-input'],
  ]);
  

  Then process with CommonMarkConverter in the controller.

• Doctrine Entities: Store Markdown in a TextType column and convert on-the-fly:

  $entity->setContent($converter->convertToHtml($rawMarkdown));
  

• Event Listeners: Modify conversion behavior via events (e.g., pre-process Markdown):

  $converter->getEnvironment()->addEventListener(
      CommonMarkEvents::PRE_PROCESS,
      function (PreProcessEvent $event) {
          $event->getMarkdown()->replace('# ', '## ');
      }
  );
  

Gotchas and Tips

Pitfalls

1. HTML Input Security:

   • html_input: allow enables raw HTML in Markdown (risky). Use sparingly or sanitize output:

     $html = $converter->convertToHtml($markdown);
     $sanitized = filter_var($html, FILTER_SANITIZE_FULL_SPECIAL_CHARS);
     

   • Prefer html_input: strict (default) to block HTML.

2. Extension Conflicts:

   • Some extensions (e.g., tables) may break rendering if misconfigured. Test thoroughly:

     {% markdown %}
     | Header 1 | Header 2 |
     |----------|----------|
     | Cell 1   | Cell 2   |
     {% endmarkdown %}
     

   • Debug with var_dump($converter->getEnvironment()->getExtensions()).

3. Caching:

   • The converter caches parsed Markdown by default. Clear cache if extensions change:

     $converter->getEnvironment()->clearCache();
     

   • Disable caching for dynamic content:

     avensome_commonmark:
         cache: false
     

4. Twig Auto-escaping:

   • Twig escapes HTML by default. Use |raw to bypass:

     {{ markdown_content | markdown | raw }}
     

   • Or configure Twig to trust the converter’s output:

     {% autoescape false %}
         {{ markdown_content | markdown }}
     {% endautoescape %}
     

5. PHP 7.4+ Deprecations:

   • Avoid createCommonMarkConverter() (deprecated in League/CommonMark). Use dependency injection:

     // ❌ Avoid
     $converter = CommonMarkConverter::createCommonMarkConverter();
     
     // ✅ Prefer
     $converter = $container->get('avensome_commonmark.converter');
     

Debugging Tips

1. Log Raw Output:

   • Inspect converted HTML for issues:

     file_put_contents(
         'debug.html',
         $converter->convertToHtml($markdown)
     );
     

2. Extension Debugging:

   • List loaded extensions:

     dd($converter->getEnvironment()->getExtensions());
     

   • Temporarily disable extensions to isolate problems:

     # services.yaml
     My\ProblematicExtension:
         tags: []
     

3. Configuration Overrides:

   • Override settings in config/packages/avensome_commonmark.yaml:

     avensome_commonmark:
         safe_mode: true  # Disables dangerous features
     

4. CommonMark CLI:

   • Test Markdown locally with the CommonMark CLI:

     commonmark --input=test.md --output=test.html
     

Extension Points

1. Custom Extensions:

   • Create a service implementing League\CommonMark\Extension\ExtensionInterface:

     class MyExtension implements ExtensionInterface {
         public function register(ContainerInterface $environment) {
             $environment->addRenderer('my_block', function () {
                 return new MyBlockRenderer();
             });
         }
     }
     

   • Tag it in services.yaml:

     My\Extension:
         tags:
             - { name: avensome_commonmark.extension }
     

2. Environment Hooks:

   • Modify the converter’s environment at runtime:

     $environment = $converter->getEnvironment();
     $environment->addExtension(new MyExtension());
     $environment->addEventListener(CommonMarkEvents::PRE_PROCESS, $listener);
     

3. Twig Customization:

   • Override the Twig filter/tag in services.yaml:

     services:
         avensome_commonmark.twig.markdown_filter:
             class: My\CustomMarkdownFilter
             arguments: ['@avensome_commonmark.converter']
             tags: ['twig.filter', 'twig.test']