Commonmark Formatter Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require core23/commonmark-formatter-bundle
   

   Ensure sonata-project/formatter-bundle is already installed (this bundle extends it).

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

   Core23\CommonMarkFormatterBundle\CommonMarkFormatterBundle::class => ['all' => true],
   

3. Configure Formatter Update config/packages/sonata_formatter.yaml:

   sonata_formatter:
       formats:
           commonmark:
               extension: '.md'
               mime_type: 'text/markdown'
               providers: ['sonata.formatter.text.html', 'sonata.formatter.text.raw']
   

4. First Use Case Create a Markdown field in a Sonata Admin entity:

   $formMapper
       ->add('content', 'sonata_formatter_type', [
           'source_key' => 'content',
           'source_field' => 'content',
           'format_field' => 'format',
           'formats' => ['commonmark'],
       ]);
   

Implementation Patterns

Workflow Integration

1. Markdown in Admin Panels Use sonata_formatter_type in Sonata Admin forms to render Markdown fields with syntax highlighting (via sonata.formatter.text.html provider).

2. Dynamic Formatting Leverage the format_field option to store the selected format (e.g., commonmark or html) in the database and apply it dynamically:

   $formatter = $this->get('sonata.formatter');
   $content = $formatter->getContent($entity->getContent(), $entity->getFormat());
   

3. Custom Providers Extend the bundle by creating a custom provider (e.g., for GitHub-flavored Markdown):

   # config/packages/sonata_formatter.yaml
   sonata_formatter:
       providers:
           - { service: 'custom.commonmark.provider', type: 'text/html' }
   

4. Twig Integration Use the formatter in Twig templates:

   {{ formatter.transform(content, format) }}
   

Common Use Cases

• Blog/News Platforms: Replace WYSIWYG editors with lightweight Markdown fields.
• Documentation Systems: Store documentation in Markdown and render it dynamically.
• API Responses: Format API documentation or error messages in Markdown.

Gotchas and Tips

Pitfalls

1. Provider Dependencies The bundle relies on sonata.formatter.text.html for HTML output. Ensure it’s installed and configured:

   composer require sonata-project/formatter-text-bundle
   

2. Caching Issues Clear the Symfony cache after installing/updating:

   php bin/console cache:clear
   

3. Markdown Parsing Quirks

   • Escaping: Use {{ content|raw }} in Twig if you need unprocessed Markdown.
   • Extensions: The bundle uses league/commonmark. For advanced features (tables, footnotes), install extensions manually:

     use League\CommonMark\Extension\Table\TableExtension;
     $configurator->addExtension(new TableExtension());
     

4. Sonata Admin Conflicts If the formatter doesn’t render in Sonata Admin, ensure:

   • The format_field is mapped to a database column (e.g., format).
   • The source_key matches the entity property name (e.g., content).

Debugging Tips

• Check Logs: Enable debug mode (APP_DEBUG=true) to inspect formatter errors.
• Inspect Providers: List available providers to debug missing formats:

  php bin/console debug:container sonata.formatter.provider
  

• Test Markdown: Use a standalone test to validate parsing:

  $markdown = "# Hello\n**World**";
  $html = $formatter->getContent($markdown, 'commonmark');
  

Extension Points

1. Custom Formatter Override the default formatter service:

   # config/services.yaml
   services:
       App\Formatter\CustomCommonMarkFormatter:
           decorates: 'sonata.formatter.commonmark'
           arguments: ['@.inner']
   

2. Post-Processing Hook into the formatter’s transform method via events (if the bundle supports them) or decorate the service.

3. Configuration Overrides Extend the bundle’s configuration in config/packages/core23_commonmark_formatter.yaml:

   core23_commonmark_formatter:
       default_options:
           html_input: 'allow'  # Allow HTML in Markdown