Commonmark Bundle Laravel Package

Product Decisions This Supports

• Roadmap Item: Enable rich text editing (e.g., Markdown support) for user-generated content (e.g., blog posts, documentation, or forum comments) in a Symfony 4+ application.
• Build vs. Buy: Avoid reinventing Markdown-to-HTML conversion by leveraging a battle-tested, Symfony-native solution instead of custom PHP logic or third-party SaaS tools (e.g., GitHub/GitLab Markdown APIs).
• Use Cases:
  • Internal Tools: Add Markdown support to admin dashboards or documentation portals.
  • Public-Facing Apps: Enable users to write content in Markdown (e.g., wikis, knowledge bases) while rendering it safely as HTML.
  • API-Driven Content: Process Markdown from external sources (e.g., GitHub/GitLab webhooks) and render it dynamically in Symfony templates.
  • Security: Sanitize user input by configuring the converter to block unsafe HTML/links (e.g., allow_unsafe_links: false).
  • Extensibility: Add custom CommonMark extensions (e.g., tables, footnotes) via Symfony’s service tags without modifying core logic.

When to Consider This Package

• Adopt if:

  • Your Symfony 4+ app needs seamless Markdown integration with Twig templates or services.
  • You require configuration control over CommonMark (e.g., disabling unsafe links, custom extensions).
  • Your team prefers PHP-native solutions over JavaScript-based Markdown libraries (e.g., React Markdown).
  • You want to avoid vendor lock-in (MIT license, no proprietary dependencies).

• Look elsewhere if:

  • You’re using Symfony 5+ (this bundle targets Symfony 4; check for newer alternatives like knplabs/knp-markdown-bundle).
  • You need real-time preview (consider frontend libraries like react-markdown or showdown).
  • Your app requires advanced Markdown features (e.g., math rendering, Mermaid diagrams) not covered by CommonMark’s core or extensions.
  • You’re not using Twig (the bundle’s Twig filters/tags are a key feature).
  • You need serverless/headless support (this is PHP-centric; evaluate frontend alternatives for JAMstack apps).

How to Pitch It (Stakeholders)

For Executives: "This package lets us add Markdown support to our Symfony app with minimal dev effort—users can write content in Markdown (e.g., for docs or blogs), and we render it safely as HTML. It’s lightweight, open-source, and integrates natively with our existing Twig templates. We can also extend it for custom features (like tables) without reinventing the wheel. This reduces dev time and improves content flexibility for [use case: e.g., customer support docs or internal wikis]."

For Engineers: *"The avensome/commonmark-bundle wraps League/CommonMark, a robust Markdown parser, and adds Symfony/Twig integration. Key perks:

• Zero config for basic use: Just install and use {{ content | markdown }} in Twig or inject CommonMarkConverter into services.
• Security controls: Disable unsafe links/HTML via config.yaml (e.g., allow_unsafe_links: false).
• Extensible: Add CommonMark extensions (e.g., tables) by tagging services—no core changes needed.
• PHP 7.0+ and Symfony 4+: Aligns with our stack. Tradeoff: Symfony 4-only (but we’re not upgrading yet). For future-proofing, we could monitor knplabs/knp-markdown-bundle for Symfony 5+ support."*

For Design/Content Teams: *"This lets you write content in Markdown (like GitHub) but renders it beautifully in our app. For example:

• Before: Writing HTML in CMS fields (error-prone, inconsistent).
• After: Writing # Headers or **bold text** in a text editor, then seeing it formatted automatically. We can also add tables, footnotes, or other features later if needed."*