패키지 분석laravel패키지html-to-markdown

Html To Markdown 패키지 분석 — 한국 Laravel 개발자 가이드

작성: 라라벨 코리아 (초안)

발행: 2026년 7월 12일

PHP용 HTML을 마크다운으로 변환해주는 헬퍼입니다.

요약

league/html-to-markdown 5.1.1은 HTML을 Markdown으로 변환해주는 PHP League 공식 패키지로, CMS 마이그레이션·사용자 입력 저장·이메일 텍스트화 등 다양한 실무 시나리오에서 활용됩니다. PHP 7.2 이상을 요구하며 MIT 라이선스로 자유롭게 사용할 수 있습니다. 보안 측면에서 신뢰할 수 없는 HTML 입력을 처리할 때 반드시 추가 설정이 필요하므로 주의가 요구됩니다.

핵심 내용

패키지 기본 정보

패키지명: league/html-to-markdown
현재 버전: 5.1.1
PHP 요구 사항: PHP 7.2 이상
PHP 확장 의존성: xml, lib-xml, dom (대부분의 배포판에서 기본 활성화)
라이선스: MIT
리드 개발자: @colinodell (league/commonmark 메인테이너와 동일 인물)

주요 기능 및 옵션 정리

옵션	기본값	설명
`strip_tags`	`false`	Markdown 미지원 태그 제거 (내용은 보존)
`remove_nodes`	`''`	지정 태그와 내용 모두 제거
`preserve_comments`	`false`	HTML 주석 보존 여부
`strip_placeholder_links`	`false`	href 없는 `<a>` 태그 처리
`bold_style`	`**`	굵게 표현 스타일 (`**` 또는 `__`)
`italic_style`	`_`	이탤릭 표현 스타일 (`*` 또는 `_`)
`hard_break`	`false`	`<br>` 변환 방식 (GFM 스타일 여부)
`use_autolinks`	`true`	자동 링크 축약 사용 여부
`header_style`	`setext`	H1/H2 헤더 스타일 (`setext` 또는 `atx`)

동작 원리

내부적으로 PHP의 DOMDocument를 사용하여 HTML 트리를 파싱한 뒤, 가장 깊은 노드부터 루트 방향으로 순회하며 각 노드를 Markdown 텍스트 노드로 치환합니다.

테이블 지원 (선택적 활성화)

Markdown 표준 스펙에 포함되지 않으므로 기본 비활성화 상태입니다. 필요 시 명시적으로 TableConverter를 등록해야 합니다.

use League\HTMLToMarkdown\HtmlConverter;
use League\HTMLToMarkdown\Converter\TableConverter;

$converter = new HtmlConverter();
$converter->getEnvironment()->addConverter(new TableConverter());

커스텀 Environment 활용

특정 컨버터만 선택적으로 등록하거나 제외할 수 있어, 변환 파이프라인을 세밀하게 제어할 수 있습니다.

$environment = new Environment(['header_style' => 'atx']);
$environment->addConverter(new HeaderConverter());

$converter = new HtmlConverter($environment);

알려진 한계

Markdown Extra, MultiMarkdown 등 확장 문법은 지원하지 않음
중첩 목록 및 블록쿼트 내 목록 변환은 아직 미완성 (To-do 항목)
링크·이미지는 인라인 방식만 지원, 각주(footnote) 스타일 미지원

한국 Laravel 개발자에게 미치는 영향

⚠️ 보안 주의 사항 (실무 최우선 확인)

README에 CAUTION 블록으로 명시되어 있듯, 이 라이브러리는 기본적으로 <span>, <div>, <iframe>, <script> 등 Markdown 미지원 태그를 그대로 보존합니다. 즉, 사용자 입력을 그대로 변환하면 XSS 등 보안 위협이 결과물에 포함될 수 있습니다.

사용자 입력을 처리하는 모든 Laravel 프로젝트에서 반드시 아래 조치 중 하나 이상을 적용하세요:

// 방법 1: strip_tags 옵션 활성화
$converter = new HtmlConverter(['strip_tags' => true]);

// 방법 2: 위험 노드 명시적 제거
$converter = new HtmlConverter(['remove_nodes' => 'script iframe style']);

// 방법 3: HTML Purifier 등 별도 라이브러리로 사전 정제 후 변환

PHP 버전 호환성

PHP 7.2 이상 요구로, Laravel 10(PHP 8.1+)·Laravel 11(PHP 8.2+) 환경에서는 모두 호환됩니다.
PHP 7.x 레거시 프로젝트와도 호환되므로, 구버전 Laravel 유지보수 환경에서도 문제없이 사용 가능합니다.

CentOS / 사내 온프레미스 서버 환경 주의

국내 기업 환경에서 자주 사용되는 CentOS 기반 서버는 php-xml 확장이 비활성화된 경우가 있습니다. DOMDocument 관련 Fatal Error가 발생한다면 아래 명령으로 확장을 설치해야 합니다.

# CentOS / RHEL 계열sudo yum install php-xml# Ubuntu / Debian 계열 (Sail, 일반 서버)sudo apt-get install php-xml

Laravel Sail / Docker 환경

공식 Sail 이미지(Ubuntu 기반)는 기본적으로 dom, xml 확장이 포함되어 있어 별도 설정 없이 사용 가능합니다. 커스텀 Dockerfile을 사용하는 경우에는 확장 설치 여부를 확인하세요.

Laravel Valet (macOS)

Homebrew로 설치된 PHP는 대부분 dom·xml 확장이 기본 포함됩니다. 별도 조치 없이 바로 사용 가능합니다.

실무 활용 시나리오

CMS/블로그 마이그레이션: 기존 WYSIWYG(TinyMCE, CKEditor 등)으로 저장된 HTML 콘텐츠를 Filament, Nova 등의 Markdown 에디터 기반으로 전환 시
노티피케이션 텍스트화: Mailable의 HTML 본문을 plain text 파트로 자동 변환
AI 프롬프트 전처리: 크롤링한 HTML 콘텐츠를 LLM에 전달하기 전 Markdown으로 정제
Markdown 저장소 구축: 사용자가 HTML로 붙여넣은 내용을 DB에 Markdown으로 통일 저장

실무 체크리스트

설치 및 초기 설정

composer require league/html-to-markdown 실행
php -m | grep -E 'xml|dom' 으로 PHP 확장 활성화 확인
CentOS 등 구형 서버라면 php-xml 패키지 설치 여부 확인

보안 설정 (사용자 입력 처리 시 필수)

strip_tags => true 또는 remove_nodes 옵션 설정 여부 검토
<script>, <iframe>, <style> 등 위험 태그가 결과물에 포함되지 않는지 테스트
필요 시 HTML Purifier 등 별도 필터 선적용 검토
변환 결과물을 다시 HTML로 렌더링하는 경우, XSS 방어 로직(e.g. {!! !!} 사용 자제)이 적용되어 있는지 확인

기능 설정 검토

테이블 변환이 필요한 경우 TableConverter 명시적 등록 확인
GFM(GitHub Flavored Markdown) 사용 환경이라면 hard_break => true 설정 검토
H1/H2 헤더 스타일: setext(기본) vs atx(#) 중 프로젝트 컨벤션에 맞게 선택
use_autolinks 옵션이 마크다운 렌더러와 호환되는지 확인

스테이징/프로덕션 배포 전

실제 운영 데이터 샘플로 변환 결과 QA 수행 (특히 중첩 목록, 테이블, 이미지 포함 HTML)
변환 결과에 중첩 목록이 포함되는 경우, 알려진 한계(미지원) 여부 확인 및 대안 마련
대용량 HTML 일괄 변환 시 메모리·타임아웃 설정 점검 (php.ini 또는 Laravel Queue 활용 권장)
composer.lock 갱신 후 스테이징에서 전체 회귀 테스트 수행

장기 유지보수

league/commonmark(Markdown→HTML)와 역방향 쌍으로 활용하는 경우, 두 패키지의 버전 업데이트 주기를 함께 관리
GitHub 저장소 릴리스 노트 구독하여 보안 패치 즉시 확인
커스텀 Environment 또는 커스텀 Converter를 작성한 경우, 버전 업그레이드 시 인터페이스 변경 여부 별도 검토

편집자 주: 이 글은 버전 5.1.1 README 및 패키지 메타데이터를 기준으로 작성된 초안입니다. 최신 CHANGELOG 및 GitHub 릴리스 노트를 함께 참고하여 버전별 변경 사항을 추가로 보완하시기 바랍니다.