Html To Markdown Laravel Package

Product Decisions This Supports

• Build vs. buy on content conversion. This is a ~1 line composer require league/html-to-markdown answer to "we need HTML → Markdown." Building an in-house converter with regex or bespoke DOM walking is a multi-week sink with a long tail of edge cases (whitespace between inline elements, placeholder links, <pre> blocks). MIT-licensed, no cost, no vendor negotiation — the decision is essentially "do we need this capability at all," not "can we afford it."
• Legacy content migration. If we're moving off a WYSIWYG/HTML CMS (WordPress, Drupal, old TinyMCE blobs) to Markdown-backed storage, this is the bulk-conversion engine. Runs cleanly inside queued Laravel jobs per record, with strip_tags, remove_nodes, preserve_comments, and strip_placeholder_links tuned per legacy source to avoid dragging along editor cruft (<span style="...">, <div> layout wrappers, tracking pixels).
• Hybrid storage / dual-format editing. Enables the "store HTML, edit Markdown" or "store Markdown, render HTML" model without committing to one canonical format forever. Note the round-trip is lossy — pair with league/commonmark for the reverse direction and treat one format as source of truth.
• Export and portability as a feature. Customer-facing "export my content as Markdown" (docs sites, GitHub, Obsidian, static site generators) is a differentiation/retention lever and an anti-lock-in trust signal. Cheap to ship on top of this package.
• AI/RAG ingestion pipelines. HTML → Markdown before chunking and embedding materially reduces token count versus raw HTML while preserving heading/list structure for retrieval quality. Relevant if we're feeding customer content into an LLM feature.
• Plain-text email fallback. The README explicitly calls out HTML-email → plain-text conversion. Useful for deliverability and accessibility in notification/newsletter flows, where a text/plain alternative part is expected.
• Roadmap shaping. Because output fidelity has known ceilings (see below), this package effectively constrains what we can promise in an editor/import epic — it argues for scoping "Markdown-native" content types rather than promising perfect conversion of arbitrary styled HTML.

When to Consider This Package

Adopt when:

• Conversion is one-directional (HTML → Markdown) or you accept lossy round-trips.
• The stack is PHP/Laravel 7.2+ and xml, libxml, dom extensions are present (watch slim/Alpine/CentOS-based containers where php-xml is stripped out — a common "works locally, fatal in prod" trap).
• Source HTML is semi-structured human content — headings, paragraphs, lists, links, images, emphasis, code blocks. That's the sweet spot.
• You need untrusted-input handling and are willing to layer HTML Purifier plus strip_tags/remove_nodes at the boundary. Default behavior preserves <script>, <iframe>, <span>, <div> — so sanitization is a hard prerequisite, not a nice-to-have.
• You want extensibility without forking: getEnvironment()->addConverter() covers custom elements; TableConverter opt-in covers GFM tables; header_style, bold_style, italic_style, hard_break, use_autolinks cover output-house-style differences.

Look elsewhere when:

• You need visual fidelity or arbitrary styled HTML preserved — reach for Pandoc (subprocess), a headless-browser pipeline, or a commercial conversion API.
• You need Markdown flavors — Markdown Extra, MultiMarkdown, and footnote-style references are explicitly unsupported; GFM is only partially addressed.
• You need nested lists or lists inside blockquotes — these sit on the package's own to-do list. Verify against a real content sample before committing; this is the most likely surprise for docs/CMS migrations.
• Round-trip fidelity matters (edit → save → edit) — pick one canonical format instead.
• Your conversion layer is Node/JS — turndown is the equivalent and would avoid a PHP↔Node hop.
• You're converting at very high volume with tight latency budgets — benchmark first; DOM parsing per document isn't free.
• Data-quality check for procurement: the "0 dependents" figure is almost certainly an artifact (this is one of the most-installed PHP conversion libraries on Packagist); confirm current download counts and the 5.x release cadence directly before citing maturity in a decision doc.

How to Pitch It (Stakeholders)

To executives: This is a mature, MIT-licensed, zero-cost component from The PHP League that removes a build-vs-buy question entirely. It unlocks three roadmap items cheaply — legacy content migration, customer-facing Markdown export, and AI-ready content ingestion — without new vendor contracts, licensing fees, or lock-in. Because it's MIT and small-surface, it's replaceable: we wrap it behind our own interface so switching costs stay low.

To engineering: One Composer dependency, PHP 7.2+, standard dom/xml extensions. Small API: instantiate HtmlConverter, call convert(), tune via config options; extend via custom converters on the Environment. No service dependency, deterministic output, trivially testable. Integration plan: a Laravel service provider + published config file for house defaults (strip_tags, header_style, use_autolinks, hard_break), an adapter interface around it, a sanitization step (HTML Purifier) upstream of any user-supplied HTML, queued jobs for bulk migration, and a golden-file test suite built from our actual content corpus to catch fidelity regressions early.

Shared risk to state up front: conversion is lossy and sanitization is mandatory — we scope it for structured content, not pixel-perfect reproduction. Known gaps (nested lists, lists in blockquotes, Markdown flavors) get validated against a real content sample in week one, before we commit the roadmap item.