웹 애플리케이션에서 고품질 PDF 문서를 생성하는 것은 오늘날 필수적인 요구사항 중 하나다. mPDF는 UTF-8 기반의 HTML을 PDF로 변환해주는 안정적이고 성숙한 PHP 라이브러리로, 복잡한 레이아웃과 다국어 지원까지 처리할 수 있다. 이 문서에서는 mPDF의 아키텍처, 핵심 기능, 성능 최적화 전략 및 실제 적용 사례를 집중적으로 분석한다.
mPDF 아키텍처와 현대 PHP 환경 호환성
mPDF는 FPDF와 HTML2FPDF를 기반으로 확장되었으며, PSR-4 자동 로딩 표준을 따르고 Mpdf\ 네임스페이스 하에 모든 클래스를 구성한다. 이는 Laravel, Symfony 등 최신 프레임워크와의 통합을 용이하게 한다.
지원되는 PHP 버전은 5.6부터 8.5까지 폭넓으며, 점진적인 업그레이드 경로를 제공해 기존 시스템의 마이그레이션 부담을 줄인다. 주요 외부 의존성으로는 PDF 조작을 위한 setasign/fpdi, 로깅 인터페이스인 psr/log, 객체 복사를 위한 myclabs/deep-copy가 있다.
핵심 기능: 유니코드 및 다국어 지원
mPDF는 전 세계 언어를 포괄적으로 지원하며, 특히 아랍어나 히브리어 같은 우측에서 좌측으로 쓰는(RTL) 스크립트도 정확히 렌더링한다. 언어별 렌더링 규칙은 src/Language/ 디렉터리에서 관리된다.
폰트 관리는 src/Fonts/ 모듈을 통해 이루어지며, 내장된 ttfonts/ 디렉터리에는 다양한 언어의 글리프를 포함한 트루타입 폰트가 포함되어 있다. 사용자는 커스텀 폰트를 추가하거나 기존 폰트를 재정의할 수 있다.
바코드 및 QR 코드 생성
mPDF는 Code128, EAN-13, UPC-A, QR Code 등 다양한 바코드 형식을 기본 제공한다. 관련 클래스는 src/Barcode/에 위치하며, 추상화 계층 덕분에 새로운 형식을 쉽게 확장할 수 있다.
성능 최적화 설정
생산 환경에서는 임시 디렉터리를 명시적으로 지정하는 것이 권장된다:
$config = [
'tempDir' => __DIR__ . '/storage/mpdf_tmp',
'fontDir' => [__DIR__ . '/custom_fonts'],
'fontdata' => require __DIR__ . '/font_data.php'
];
$pdf = new \Mpdf\Mpdf($config);
또한 다음과 같은 성능 향상 기능을 활용할 수 있다:
- 폰트 서브셋팅(subsetting): 출력 파일 크기 감소
- 이미지 자동 압축: JPEG/PNG 최적화
- 캐시 시스템: 반복 사용 리소스 재사용
실무 적용 예시
청구서 및 보고서 생성 시, 페이지 머리글과 꼬리글을 동적으로 설정할 수 있다:
$pdf = new \Mpdf\Mpdf();
$pdf->SetHTMLHeader('<div style="text-align:right">회사명 | {DATE j-m-Y}</div>');
$pdf->SetHTMLFooter('<div style="text-align:center">{PAGENO} / {nbpg}</div>');
다국어 문서의 경우, mPDF는 입력 텍스트를 분석해 적절한 폰트와 방향성을 자동으로 선택한다. 단, 해당 언어를 지원하는 폰트가 사전에 등록되어 있어야 한다.
모던 PHP 통합 패턴
mPDF 8.1 이상 버전은 서비스 컨테이너를 도입하여 의존성 주입을 지원한다:
$container = new \Mpdf\Container\SimpleContainer();
$pdf = $container->get(\Mpdf\Mpdf::class);
출력 방식도 다양해졌다:
Output(): 기본 출력 (브라우저 인라인 또는 다운로드)Output('filename.pdf', 'F'): 파일 저장Output('', 'S'): 문자열 반환 (API 응답용)
문제 해결 및 디버깅
디버그 모드를 활성화하면 상세 로그를 기록할 수 있다:
$pdf = new \Mpdf\Mpdf([
'debug' => true,
'logOutputFile' => __DIR__ . '/logs/mpdf.log'
]);
자주 발생하는 문제와 해결책:
- 한글 깨짐: Noto Sans CJK 또는 NanumGothic 같은 CJK 폰트를 등록하고 CSS에서 명시적으로 지정
- 메모리 부족:
memory_limit을 512M 이상으로 설정 - 이미지 로드 실패: GD 또는 Imagick 확장 모듈 설치 확인
업그레이드 및 확장 개발
mPDF 7.x → 8.x 마이그레이션 시 주의사항:
- 클래스 이름이
mPDF에서\Mpdf\Mpdf로 변경됨 - 생성자 인자가 배열 형태로 통일됨
- 기존
config.php대신 직접 설정 배열 사용
커스텀 HTML 태그를 지원하려면 src/Tag/ 디렉터리의 클래스를 상속하여 구현할 수 있다. 예를 들어, <invoice-item> 같은 비표준 태그를 정의해 반복 청구 항목을 간결하게 표현 가능하다.
리소스 관리 권장 사항
- 폰트는 사용 빈도에 따라 동적으로 로드하거나 캐시 활용
- 큰 이미지는 미리 리사이징 후 삽입
- 소형 아이콘은 base64 인코딩으로 HTML 내 인라인 포함
mPDF는 복잡한 CSS 레이아웃보다는 서버 측에서의 안정적이고 대량의 문서 생성에 특화되어 있다. 특히 오프라인 인쇄, 법적 문서, 국제화된 보고서 등에서 여전히 강력한 솔루션으로 자리잡고 있다.