Markdown Laravel Package

Technical Evaluation

Architecture fit — the headline issue. This is not a Laravel package. flarum/markdown is an extension for Flarum, a standalone PHP forum application that borrows Laravel's illuminate/* components but has its own bootstrapping, extension API (Flarum\Extend), asset pipeline, and frontend (Mithril/JS bundles). It registers itself through Flarum's Formatter contract and extend.php, not through a Laravel service provider. In a Laravel app there is no correct seam to hook it into; composer require flarum/markdown alongside Laravel will attempt to pull Flarum core contracts and fight over illuminate/* version constraints. Fit is therefore binary: excellent if we are running Flarum, near-zero if we are not.

What it actually provides. A CommonMark render pipeline built on s9e/text-formatter, with a hardened, allowlisted HTML config (the reason it is safe against stored XSS), a set of Flarum-specific s9e plugins, and a rendered-output cache persisted per post so that parsing is a one-time cost per post per config version. That caching behaviour is the most operationally significant thing in the package.

Integration feasibility. Low as a library, high as a deployment. Realistic paths, in order of preference: (1) run Flarum as a companion service and take the extension for free; (2) if the requirement is only "render Markdown in our Laravel app," use league/commonmark or s9e/text-formatter directly and borrow this package's config as a reference; (3) fork the formatter config into an internal package only if several PHP services must render identically.

Technical risk.

• Framework mismatch — highest risk, and the one that kills the naive plan.
• Metadata inconsistency: the last release is dated 2026-10-14, in the future. Verify the real tag and changelog before pinning anything.
• 17 stars / 0 dependents reads as abandonment but isn't — this extension ships with Flarum core, so it has enormous real-world usage and almost no standalone visibility. The consequence is not risk of death, it is risk of no independent documentation, tutorials, or StackOverflow answers.
• Version coupling to a Flarum major line; a mismatch is a hard boot failure, not a degraded mode.
• Markdown-to-HTML is a persistent XSS surface. Safety comes from the upstream s9e allowlist being left alone; any local loosening transfers that risk to us permanently, across all historical content.

Key questions.

• Is the requirement "we need a forum" or "we need Markdown rendering"? This single answer decides the whole assessment.
• Which Flarum major are we on, and does the extension's constraint match?
• Do we need the Flarum-specific plugins (mentions, quotes, spoilers), or plain CommonMark?
• Who owns the sanitization policy — upstream config, or us?
• Does a cached-render model fit our need to retroactively re-render old content (new link policy, new emoji, new mention syntax)?
• Is the 2026-10-14 release real, and what changed in it?

Integration Approach

Stack fit. Same runtime (PHP 8.x), same package manager, adjacent ecosystem — but not the same framework. Treat it as "PHP-ecosystem adjacent," not "Laravel package." If we stand up Flarum as the community surface (a very common Laravel + Flarum pattern, forum at /community), this extension is the default post formatter: zero integration code, configuration only.

Migration paths, with rough effort.

1. Flarum as companion service — recommended if the requirement is a forum. Flarum runs as its own PHP service, SSO from Laravel via a signed token or an auth extension, reverse proxy at /community. Markdown support is included. Effort: days, mostly SSO and theming.
2. Native Laravel Markdown — recommended if the requirement is inline Markdown in our own UI. league/commonmark plus a MarkdownRenderer service, a Blade component, and an explicit sanitizer allowlist. Port the mention/quote/spoiler config from this package only if we need parity. Effort: 1–3 days.
3. Internal shared formatter package — only if multiple PHP services must render identically. Effort: 1–2 weeks including a golden-file corpus.
4. Require it inside Laravel — do not. Transitive illuminate/* conflicts with our Laravel major, and the usable surface is zero.

Compatibility checks before committing. PHP constraint vs. our 8.2/8.3 target; the transitive illuminate/* range vs. our Laravel major (this is the concrete collision in option 4); frontend assets are prebuilt Flarum JS bundles published via php flarum assets:publish, with no overlap with a Vite build — don't plan on merging the two build pipelines.

Sequencing.

1. One-day spike to settle forum-vs-inline. Everything downstream depends on it.
2. Define the content contract first: store Markdown source as the source of truth; rendered output is cache only, never canonical. Getting this wrong is expensive to reverse.
3. Forum path: provision Flarum in staging, pin the version, put it behind the proxy, wire SSO, theme last.
4. Inline path: renderer service, sanitizer allowlist, and golden tests first; editor and preview UI second.
5. Either way, commit a render-parity corpus (nested lists, raw HTML, javascript: links, tables, mentions) so any future formatter swap is verifiable rather than hopeful.

Operational Impact

Maintenance. Low on the Flarum path — it is core-bundled and maintained by the Flarum team, and upgrades arrive with Flarum upgrades. High if forked or forced into a non-Flarum app, because we then own a bespoke fork. Plan for one Flarum major upgrade every ~18–24 months; each requires re-validating the formatter config and clearing the render cache.

Support. Community only. With 17 stars there is no third-party knowledge base; the channels are the Flarum Discuss forum and GitHub issues. No vendor SLA. Whoever does the spike must write the internal runbook, because it will be the only internal documentation that exists.

Scaling. The formatter is CPU-bound per post, mitigated by the persisted render cache — so steady state is cheap and stateless, and horizontal scaling is fine. Cost concentrates in three places: first render of a new post (negligible), preview requests during composition (debounce and rate-limit if we build our own UI, or we will effectively DDoS ourselves), and bulk re-render after any config change, which is O(all posts) — budget a queue-backed backfill job and a maintenance window for that, not a request-path operation.

Failure modes.

• Config change without a cache flush → silently stale rendering on all historical posts.
• Extension version drift vs. Flarum core → Flarum refuses to boot. Site down, not degraded. Pin versions in composer.json and in the deploy image.
• Render-cache schema change across a Flarum major → 500s on every post view.
• Any loosening of the sanitizer config → persistent stored XSS across the corpus. Highest severity, lowest visibility, effectively irreversible once content is stored.
• Misreading 17 stars / 0 dependents as "abandoned," leading to an unnecessary fork or a swap to an unvetted alternative.
• Future-dated release metadata producing a bad version pin.

Ramp-up. ~1 day to read extend.php, the Formatter subclass, and the s9e config well enough to be dangerous; ~1 week to be genuinely productive with the Flarum extension system (extenders, migrations, settings, asset publishing). Note that Laravel experience transfers poorly here — same language, different framework, different asset pipeline. The league/commonmark alternative ramps in hours and the knowledge is portable across the PHP ecosystem, which is a real, if unglamorous, argument in its favour.