콘텐츠 대표 이미지 - PHP로 PDF 정복하기: 단순 생성부터 고급 조작까지, 개발자 A to Z 가이드

PHP로 PDF 정복하기: 단순 생성부터 고급 조작까지, 개발자 A to Z 가이드

웹 개발하다 보면 꼭 마주치는 PDF! 인보이스, 리포트, 티켓...
더 이상 피하지 말고 PHP로 자유자재로 가지고 노는 법, 지금부터 내가 전부 알려줄게.

안녕, 개발자 친구! 👋

코딩하다 보면 그런 순간 꼭 오지 않아? "아, 이거 PDF로 뽑아줘야 하는데..." 하는 순간 말이야.
고객사에서는 매달 거래명세서를 PDF로 받고 싶어 하고, 쇼핑몰에서는 주문 확인서를, 공연 예매 사이트에서는 티켓을 PDF로 제공해야 하지. 이메일로 보내는 리포트나 이력서 같은 것도 마찬가지고.

HTML로 화면에 보여주는 건 자신 있는데, 이걸 그대로 인쇄 가능한, 포맷이 고정된 파일로 만들려니 막막했던 경험, 다들 한 번쯤 있을 거야. 브라우저의 '인쇄' 버튼에만 의존하기엔 디자인이 깨지고 영 모양이 안 나잖아. 바로 이럴 때 우리에게 필요한 게 서버 사이드에서 PDF를 직접 생성하는 기술이야.

그런데 PHP 자체에는 PDF를 만드는 기능이 없어. 마치 기본 옵션 자동차에 내비게이션이 없는 것처럼 말이지. 그럼 어떡하냐고? 걱정 마. 우리에겐 강력한 '라이브러리'라는 튜닝 파츠가 있으니까! 이 글에서는 PHP 개발자라면 누구나 알아야 할 PDF 생성 및 조작 라이브러리들을 A부터 Z까지, 아주 친절하고 깊이 있게 파헤쳐 볼 거야.

단순히 'Hello World'를 찍는 수준을 넘어서, HTML/CSS를 그대로 PDF로 변환하고, 커스텀 폰트를 적용하고, 헤더와 푸터를 넣고, 심지어 기존 PDF 파일을 수정하거나 합치는 고급 기술까지! 내가 차근차근 다 떠먹여 줄게. 이 글 하나만 마스터하면, 앞으로 PDF 관련 요구사항은 전혀 두렵지 않게 될 거라고 장담해. 자, 그럼 엔진 시동 걸고 출발해 볼까?

🤔 잠깐, 왜 하필 PDF일까?

라이브러리를 살펴보기 전에, 우리가 왜 이렇게 PDF에 집착(?)하는지 잠깐 짚고 넘어가자. PDF는 'Portable Document Format'의 약자야. 이름 그대로 '휴대용 문서 형식'이라는 뜻이지.

1993년, 어도비(Adobe)에서 만들었는데, 당시의 목표는 아주 명확했어. **"어떤 컴퓨터, 어떤 운영체제, 어떤 프로그램에서 열어도 항상 똑같은 모양으로 보이는 문서를 만들자!"**

이게 왜 혁신이었냐면, 그 시절엔 아래아 한글 파일(.hwp)을 MS 워드에서 열면 글자가 깨지고 레이아웃이 와장창 무너지는 일이 비일비재했거든. 내가 만든 멋진 문서를 남에게 보냈는데, 그 사람 컴퓨터에선 외계어처럼 보이면 얼마나 슬퍼. PDF는 바로 이 문제를 해결하기 위해 태어난 디지털 시대의 종이인 셈이야.

✨ PDF가 사랑받는 이유 Top 3

1. **플랫폼 독립성 (WYSIWYG):** What You See Is What You Get! 윈도우, 맥, 리눅스, 스마트폰 어디서 열든 내가 만든 모습 그대로 보여. 폰트가 없거나 프로그램이 달라도 걱정 없지. 이게 바로 '전자 문서의 표준'으로 자리 잡은 가장 큰 이유야.

2. **보안 기능:** PDF는 문서에 암호를 걸거나, 인쇄/복사/편집을 제한하는 등 다양한 보안 설정을 할 수 있어. 중요한 계약서나 대외비 문서를 안전하게 전달하기에 딱이지.

3. **인쇄 최적화:** PDF는 벡터 기반이라 아무리 확대해도 이미지가 깨지지 않고, 인쇄했을 때의 결과물이 화면과 거의 동일해. 그래서 인쇄소에 파일을 넘길 때도 PDF를 선호하는 거야.

이런 특징들 때문에 웹 애플리케이션에서 생성되는 각종 증명서, 보고서, 명세서 등 '공식적인' 문서는 대부분 PDF 형식을 사용하는 거야. 자, 이제 PDF의 위대함을 충분히 느꼈으니, 본격적으로 PHP로 PDF를 요리하는 방법을 알아보자.

🛠️ 연장 챙기기: 나에게 맞는 PHP PDF 라이브러리 선택 가이드

PHP로 PDF를 만들려면 라이브러리가 필수라고 했지? 근데 이 라이브러리 종류가 생각보다 꽤 많아. 각각 장단점과 사용법이 달라서, 프로젝트 성격에 맞는 녀석을 고르는 게 정말 중요해. 무작정 남들이 쓴다고 따라 쓰다간 개발 과정이 고통스러워질 수도 있거든.

주요 라이브러리들을 내가 비교 분석해 줄게. 잘 보고 네 상황에 맞는 최적의 파트너를 찾아봐!

PHP PDF 라이브러리 선택 플로우 내 프로젝트는? 기존 HTML/CSS 템플릿을 그대로 PDF로 만들고 싶나? YES mPDF / Dompdf CSS 지원이 중요! 대부분의 웹 개발에 가장 편리함 NO TCPDF / FPDF 좌표 기반의 정밀한 제어가 필요 (바코드, 폼 채우기 등) 최고의 렌더링 품질이 필요하고 서버에 프로그램 설치가 가능하다면? Snappy

1. mPDF: HTML/CSS 변환의 최강자

  • 특징: HTML과 CSS를 PDF로 변환하는 데 있어서는 거의 끝판왕급 라이브러리. 복잡한 CSS도 꽤 잘 해석하고, 특히 UTF-8(한글 포함) 지원이 아주 훌륭해. 테이블, float, 폰트 임베딩, 헤더/푸터, 워터마크 등 필요한 기능은 거의 다 갖추고 있어.
  • 장점: 기존에 만들어둔 HTML 템플릿을 거의 그대로 재활용할 수 있어서 개발 속도가 매우 빠르다. 문서화도 잘 되어 있고 커뮤니티도 활발하다.
  • 단점: 기능이 많은 만큼 라이브러리 자체가 무겁고, 복잡한 HTML을 변환할 땐 메모리를 많이 사용하고 속도가 느려질 수 있다.
  • 추천 대상: **대부분의 웹 개발자.** 인보이스, 리포트, 증명서 등 디자인된 HTML 문서를 PDF로 만들어야 하는 거의 모든 경우에 최고의 선택이야.

2. Dompdf: mPDF의 훌륭한 경쟁자

  • 특징: mPDF와 마찬가지로 HTML/CSS를 PDF로 변환하는 라이브러리. CSS 2.1 스펙을 잘 따르고, 외부 라이브러리 의존성이 적어서 설치가 비교적 간단하다.
  • 장점: mPDF보다 가볍고 빠르다는 평이 있다 (물론 케바케). 기본적인 기능에 충실하다.
  • 단점: mPDF에 비해 지원하는 CSS 속성이나 고급 기능(예: 복잡한 테이블 렌더링)이 다소 부족할 수 있다. 한글 폰트 설정이 mPDF보다 조금 더 까다로울 수 있다.
  • 추천 대상: 비교적 간단한 HTML 문서를 빠르게 변환하고 싶을 때. mPDF가 너무 무겁게 느껴진다면 좋은 대안이 될 수 있다.

3. TCPDF: 정밀 제어의 명장

  • 특징: HTML 변환보다는 PHP 코드로 직접 PDF의 모든 요소를 그리는 방식에 특화되어 있어. `SetXY()`, `Cell()`, `Line()` 같은 함수를 써서 "x, y 좌표에 이 텍스트를 쓰고, 저기서부터 저기까지 선을 그어라" 와 같이 명령을 내리는 식이야.
  • 장점: 좌표 기반이라 아주 정밀한 레이아웃 제어가 가능하다. 바코드, QR코드 생성, 디지털 서명 등 HTML 변환 방식으로는 힘든 강력한 기능들을 내장하고 있다.
  • 단점: 모든 걸 코드로 그려야 하니, 복잡한 문서를 만들려면 코드가 매우 길고 지저분해질 수 있다. HTML/CSS의 편리함은 포기해야 한다.
  • 추천 대상: 정부 양식처럼 정해진 칸에 정확히 내용을 채워 넣어야 할 때, 바코드나 QR코드가 반드시 필요할 때.

4. FPDF: 클래식은 영원하다

  • 특징: PHP PDF 라이브러리의 시조새 격. 아주 오래됐지만 그만큼 안정적이고 가볍다. TCPDF처럼 코드로 직접 PDF를 그리는 방식이지만, 기능은 훨씬 단순하다.
  • 장점: 정말 가볍고 빠르다. 외부 의존성이 전혀 없어서 그냥 파일 몇 개만 올리면 바로 쓸 수 있다.
  • 단점: **UTF-8(한글)을 기본으로 지원하지 않는다!** 별도의 확장과 폰트 변환 작업을 거쳐야 해서 매우 번거롭다. 기능도 가장 기본적이라 요즘 쓰기엔 부족함이 많다.
  • 추천 대상: 정말 정말 간단한 영문 텍스트 위주의 PDF를 만들어야 할 때. 혹은 레거시 시스템을 유지보수해야 할 때. (솔직히 요즘 새로 시작하는 프로젝트에는 추천하지 않아.)

💡 결론: 뭘 써야 할까?

90% 이상의 상황에서는 **mPDF**를 선택하면 후회하지 않을 거야. 개발 생산성이 넘사벽이거든. 만약 mPDF가 너무 무겁거나 특정 기능에서 문제가 생긴다면 **Dompdf**를 고려해보고, 좌표 기반의 정밀 제어나 바코드 같은 특수 기능이 필요하다면 **TCPDF**를 쳐다보면 돼. FPDF는... 그냥 이런 게 있었다 정도로만 알아두자! 😉

이런 라이브러리들을 자유자재로 다루는 능력은 개발자로서 큰 무기가 될 수 있어. 나중에 프리랜서로 활동하거나 할 때 재능넷 같은 플랫폼에 'PHP PDF 전문가'로 프로필을 등록하면 꽤 많은 기회를 잡을 수 있을걸?

자, 이제 라이브러리 선택도 끝났으니 실전에 들어가 봐야지? 가장 범용적이고 강력한 **mPDF**를 중심으로 깊이 있게 파고들어 볼 거야. TCPDF의 특수 기능과 기존 PDF를 조작하는 팁도 뒤에서 다룰 테니 끝까지 집중해 줘!

🚀 실전! mPDF로 PDF 만들기 (A to Z)

백문이 불여일견! 직접 코드를 짜면서 mPDF의 강력함을 느껴보자. 요즘 PHP 개발의 표준인 '컴포저(Composer)'를 사용해서 설치부터 시작할 거야. 만약 컴포저가 낯설다면, 이번 기회에 꼭 익숙해지는 걸 추천해. PHP 생태계의 필수 도구거든.

1. 설치: 컴포저로 10초 컷

프로젝트 폴더에서 터미널을 열고 아래 명령어를 입력해. 끝!

composer require mpdf/mpdf

이 명령어 하나면 mPDF 라이브러리와 그에 필요한 모든 의존성 파일들이 `vendor` 폴더 안에 자동으로 설치돼. 정말 편하지?

2. "Hello, PDF World!" - 기본 사용법

가장 먼저, 간단한 텍스트와 HTML 태그가 포함된 PDF를 만들어보자. `create_pdf.php` 같은 파일을 하나 만들고 아래처럼 코드를 작성해봐.

create_pdf.php

<?php
// 1. 컴포저의 오토로더를 불러온다. (필수!)
require_once __DIR__ . '/vendor/autoload.php';

// 2. mPDF 객체를 생성한다.
$mpdf = new \Mpdf\Mpdf();

// 3. WriteHTML() 메소드를 사용해서 PDF에 들어갈 내용을 적는다.
// HTML 태그를 마음껏 사용할 수 있어!
$mpdf->WriteHTML('<h1>Hello PDF World!</h1>');
$mpdf->WriteHTML('<p>이것은 mPDF를 사용하여 생성한 첫 번째 PDF 문서입니다.</p>');
$mpdf->WriteHTML('<em>HTML 태그도 잘 먹히네요!</em>');

// 4. Output() 메소드로 PDF를 출력한다.
$mpdf->Output();

// 끝!
?>

이제 웹 브라우저에서 이 PHP 파일을 실행해봐. (예: `http://localhost/create_pdf.php`)
어때? 'Hello PDF World!'라는 제목의 PDF 파일이 브라우저에 바로 나타나지? 이게 mPDF의 가장 기본적인 작동 방식이야. 너무 간단해서 놀랐지?

💡 `Output()` 메소드의 4가지 모드 (이거 진짜 중요!)

`Output()` 함수는 파라미터에 따라 다르게 동작해. 이건 꼭 알아둬야 해.

  • `$mpdf->Output();` 또는 `$mpdf->Output('filename.pdf', 'I');`
    => **I (Inline):** 브라우저에 PDF를 바로 보여준다. (기본값)
  • `$mpdf->Output('my_document.pdf', 'D');`
    => **D (Download):** 브라우저가 'my_document.pdf'라는 이름으로 파일 다운로드 창을 띄운다.
  • `$mpdf->Output('/path/to/save/invoice.pdf', 'F');`
    => **F (File):** 서버의 지정된 경로에 'invoice.pdf'라는 이름으로 파일을 저장한다. 사용자에게 보여주지 않고 서버에만 기록할 때 사용.
  • `$pdf_string = $mpdf->Output('', 'S');`
    => **S (String):** PDF 파일의 내용을 문자열(string) 형태로 반환한다. 이메일 첨부파일로 보내는 등 후처리가 필요할 때 유용하다.

상황에 맞게 이 네 가지 모드를 잘 활용하는 게 mPDF 고수의 첫걸음이야.

3. 스타일링: CSS로 PDF 꾸미기

단순히 텍스트만 넣을 거면 PDF를 쓰는 의미가 없지. mPDF의 진가는 CSS를 사용해서 문서를 예쁘게 꾸밀 수 있다는 데 있어. 방법은 크게 세 가지야.

방법 1: `WriteHTML()`에 스타일 블록 직접 넣기

HTML 문자열 안에 `style` 태그를 포함시키는 가장 간단한 방법이야.

<?php
require_once __DIR__ . '/vendor/autoload.php';
$mpdf = new \Mpdf\Mpdf();

$html = '
<style>
    h1 {
        color: steelblue;
        text-align: center;
    }
    p {
        font-size: 14px;
        color: #333;
    }
    .highlight {
        background-color: yellow;
        font-weight: bold;
    }
</style>

<h1>CSS로 스타일링하기</h1>
<p>이 문서는 <span class="highlight">CSS 스타일</span>이 적용되었습니다.</p>
';

$mpdf->WriteHTML($html);
$mpdf->Output();
?>

방법 2: 외부 CSS 파일 불러오기

스타일이 복잡해지면 CSS를 별도 파일로 관리하는 게 좋겠지? `WriteHTML()`은 똑똑하게도 HTML 안의 `` 태그를 해석해서 CSS 파일을 불러올 수 있어.

먼저 `style.css` 파일을 만들자.

style.css

body {
    font-family: sans-serif;
}
h1 {
    color: #b91c1c; /* red-700 */
    border-bottom: 2px solid #fecaca; /* red-200 */
}
/* ... 기타 스타일들 ... */

그리고 PHP 파일에서 이 CSS를 링크하는 거야.

create_pdf_with_css_file.php

<?php
require_once __DIR__ . '/vendor/autoload.php';
$mpdf = new \Mpdf\Mpdf();

// file_get_contents로 CSS 파일 내용을 읽어와서 WriteHTML로 먼저 써준다.
// 이게 가장 안정적으로 작동하는 방법이야.
$stylesheet = file_get_contents('style.css');
$mpdf->WriteHTML($stylesheet, \Mpdf\HTMLParserMode::HEADER_CSS);

// 그 다음 본문 HTML을 쓴다.
$html = '<h1>외부 CSS 파일 적용</h1><p>CSS 파일이 잘 링크되었습니다.</p>';
$mpdf->WriteHTML($html, \Mpdf\HTMLParserMode::HTML_BODY);

$mpdf->Output();
?>

여기서 중요한 점! `WriteHTML`의 두 번째 파라미터로 `\Mpdf\HTMLParserMode::HEADER_CSS`를 주면, mPDF가 이 내용을 스타일시트로 인식해. 그 다음에 본문 HTML을 `HTML_BODY` 모드로 써주는 거지. 이렇게 분리해서 처리하는 게 복잡한 CSS에서 발생할 수 있는 오류를 줄여주는 꿀팁이야.

⚠️ CSS 지원 한계: mPDF가 대단하긴 하지만 모든 최신 CSS를 다 지원하는 건 아니야. Flexbox나 Grid 같은 최신 레이아웃 시스템은 지원이 완벽하지 않을 수 있어. 주로 CSS 2.1 표준을 기반으로 작동한다고 생각하면 돼. float, position, table 레이아웃은 잘 작동하니 이걸 중심으로 레이아웃을 짜는 게 좋아. 지원되는 CSS 목록은 공식 문서를 꼭 확인해봐!

4. 한글 폰트 적용: 더 이상 깨지지 말자! (가장 중요)

mPDF를 쓰면서 한국 개발자들이 가장 처음 부딪히는 벽이 바로 '한글 깨짐' 현상이야. 기본 폰트에는 한글 글자가 없어서 생기는 문제지. 해결책은 아주 간단해. **한글을 지원하는 폰트를 지정해주면 돼.**

mPDF 7.0 이상부터는 설정이 훨씬 쉬워졌어. 객체를 생성할 때 폰트 설정을 해주면 돼.

먼저, 사용할 한글 폰트 파일(.ttf)을 준비해야 해. 구글의 'Noto Sans KR'이나 네이버의 '나눔고딕' 같은 무료 폰트를 추천해. 프로젝트 폴더 안에 `fonts` 같은 폴더를 만들고 그 안에 `NotoSansKR-Regular.ttf` 파일을 넣어두자.

create_pdf_with_korean.php

<?php
require_once __DIR__ . '/vendor/autoload.php';

// 1. 기본 폰트 설정 추가
$defaultConfig = (new Mpdf\Config\ConfigVariables())->getDefaults();
$fontDirs = $defaultConfig['fontDir'];

$defaultFontConfig = (new Mpdf\Config\FontVariables())->getDefaults();
$fontData = $defaultFontConfig['fontdata'];

// 2. mPDF 객체 생성 시 설정 전달
$mpdf = new \Mpdf\Mpdf([
    // 사용할 폰트 경로 추가
    'fontDir' => array_merge($fontDirs, [
        __DIR__ . '/fonts',
    ]),
    // 사용할 폰트 등록
    'fontdata' => $fontData + [
        'notosanskr' => [ // CSS에서 'font-family: notosanskr;' 로 사용될 이름
            'R' => 'NotoSansKR-Regular.ttf',
            // 'B' => 'NotoSansKR-Bold.ttf', // 볼드체 등 다른 스타일도 추가 가능
        ]
    ],
    // 기본 폰트 지정
    'default_font' => 'notosanskr'
]);

// 이제 한글을 마음껏 써도 돼!
$mpdf->WriteHTML('<h1>안녕하세요, mPDF!</h1>');
$mpdf->WriteHTML('<p>이제 한글이 깨지지 않고 아주 잘 나옵니다. 정말 멋지네요!</p>');

$mpdf->Output('한글문서.pdf', 'I');
?>

코드가 조금 길어졌지만 원리는 간단해.
1. mPDF의 기본 설정을 불러와서
2. 내가 사용할 폰트가 있는 폴더(`fontDir`)와 폰트 정보(`fontdata`)를 추가하고
3. 이 설정으로 mPDF 객체를 만드는 거야.
4. `default_font`를 지정해주면 문서 전체의 기본 폰트가 바뀌고, CSS에서 `font-family: notosanskr;` 처럼 특정 요소에만 폰트를 적용할 수도 있어.

이 코드 조각만 잘 저장해두면 앞으로 한글 때문에 고생할 일은 없을 거야!

5. 헤더 & 푸터: 문서의 완성도 높이기

보고서나 인보이스에는 보통 회사 로고, 문서 제목, 페이지 번호 같은 게 상단(헤더)이나 하단(푸터)에 반복적으로 들어가잖아. mPDF는 이것도 아주 쉽게 처리할 수 있어.

간단한 텍스트 헤더/푸터

// 헤더 설정: {PAGENO}는 현재 페이지 번호, {nb}는 전체 페이지 번호
$mpdf->SetHeader('내 회사 문서|가운데 텍스트|{PAGENO}/{nb}');
// 푸터 설정: {DATE j-m-Y}는 오늘 날짜
$mpdf->SetFooter('비밀문서|{DATE j-m-Y}| Confidential');

$mpdf->WriteHTML('내용...');
$mpdf->Output();

`SetHeader`와 `SetFooter` 함수의 파이프(|) 문자는 왼쪽|가운데|오른쪽 영역을 구분하는 역할을 해.

HTML을 사용한 고급 헤더/푸터

단순 텍스트가 아니라 로고 이미지나 복잡한 표를 헤더/푸터에 넣고 싶을 수도 있겠지? 당연히 가능해.

<?php
require_once __DIR__ . '/vendor/autoload.php';
$mpdf = new \Mpdf\Mpdf();

// HTML로 헤더 정의
$header = '
<table width="100%">
    <tr>
        <td width="33%"><img src="logo.png" width="100px" /></td>
        <td width="33%" align="center">월간 보고서</td>
        <td width="33%" style="text-align: right;">2023년 10월</td>
    </tr>
</table>';

// HTML로 푸터 정의
$footer = '
<div style="border-top: 1px solid #000; font-size: 10px; text-align: center; padding-top: 3mm;">
    Page {PAGENO} of {nb}
</div>';

$mpdf->SetHTMLHeader($header);
$mpdf->SetHTMLFooter($footer);

// 본문 내용
$mpdf->WriteHTML('<h1>본문 제목</h1><p>이 문서는 HTML 헤더와 푸터를 가지고 있습니다.</p>');
// 페이지를 넘겨서 헤더/푸터가 잘 나오는지 확인
$mpdf->AddPage();
$mpdf->WriteHTML('<h1>두 번째 페이지</h1><p>여기도 헤더와 푸터가 잘 보입니다.</p>');

$mpdf->Output();
?>

`SetHTMLHeader()`와 `SetHTMLFooter()`를 쓰면 돼. HTML로 만들 수 있으니 디자인 자유도가 엄청나게 높아지겠지? 이미지 경로(`src="logo.png"`)는 PHP 파일 기준으로 상대 경로를 사용하면 돼.

6. 기타 유용한 기능들

  • 페이지 나누기: HTML 내용 중간에 `` 태그를 넣으면 그 위치에서 다음 페이지로 넘어가.
  • 워터마크: `SetWatermarkText('DRAFT')` 처럼 텍스트 워터마크를 넣거나, `SetWatermarkImage('watermark.png')`로 이미지 워터마크를 넣을 수 있어.
  • 목차 생성: `

    `, `

    ` 같은 태그에 맞춰서 자동으로 목차를 만들어주는 기능도 있어. `$mpdf->TOCpagebreak()`를 사용하면 돼.

  • 가로 방향 페이지: `$mpdf = new \Mpdf\Mpdf(['mode' => 'utf-8', 'format' => 'A4-L']);` 처럼 객체 생성 시 포맷 뒤에 `-L`을 붙이거나, `$mpdf->AddPage('L');` 처럼 특정 페이지만 가로로 만들 수도 있어.

mPDF의 기능은 정말 무궁무진해. 이 글에서 모든 걸 다룰 순 없지만, 이 정도만 알아도 웬만한 PDF는 다 만들 수 있을 거야. 더 자세한 기능은 공식 문서를 탐험해보는 걸 추천해!

🔩 고급 기술: 기존 PDF 조작하고 합치기

지금까지는 새로운 PDF를 '생성'하는 법을 배웠어. 그런데 실무에서는 이미 만들어진 PDF를 '조작'해야 하는 경우도 많아. 예를 들어, 여러 개의 PDF 리포트를 하나로 합치거나, 기존 PDF 양식 위에 내용만 채워 넣는 작업 같은 거 말이야.

이런 작업을 할 때 필요한 라이브러리가 바로 **FPDI**야. FPDI는 단독으로 쓰이는 라이브러리가 아니라, FPDF나 TCPDF와 함께 사용해서 기존 PDF 파일의 페이지를 '템플릿'처럼 가져올 수 있게 해주는 마법 같은 녀석이야.

mPDF도 FPDI를 내장하고 있어서 추가 설치 없이 바로 사용할 수 있어. 정말 최고지?

1. 여러 PDF 파일 하나로 합치기 (Merging)

`report-1.pdf`, `report-2.pdf` 두 개의 파일을 합쳐서 `merged-report.pdf`로 만들어보자.

<?php
require_once __DIR__ . '/vendor/autoload.php';

$mpdf = new \Mpdf\Mpdf();

// 합칠 파일 목록
$files = ['report-1.pdf', 'report-2.pdf'];

foreach ($files as $file) {
    // setSourceFile()로 원본 PDF 파일을 지정
    $pageCount = $mpdf->setSourceFile($file);

    // 원본 PDF의 모든 페이지를 순회하며 추가
    for ($i = 1; $i <= $pageCount; $i++) {
        // importPage()로 페이지를 가져온다
        $templateId = $mpdf->importPage($i);
        // useTemplate()으로 현재 PDF에 추가한다
        $mpdf->useTemplate($templateId);
        
        // 마지막 페이지가 아니면 새 페이지 추가
        if ($i < $pageCount) {
            $mpdf->AddPage();
        }
    }
    // 다음 파일을 위해 새 페이지 추가 (파일 사이에 페이지 구분)
    if (next($files)) {
        $mpdf->AddPage();
    }
}

$mpdf->Output('merged-report.pdf', 'F'); // 파일로 저장
echo "PDF 합치기 완료!";
?>

핵심은 `setSourceFile()`로 원본을 열고, `importPage()`로 페이지를 하나씩 떠온 다음, `useTemplate()`으로 현재 문서에 붙여넣는 과정이야. 이 로직만 이해하면 몇십 개든 몇백 개든 합칠 수 있어.

2. PDF 템플릿 위에 글자 쓰기 (Stamping)

이게 진짜 실무 꿀팁이야. 디자이너에게 미리 예쁘게 만들어진 PDF 양식(예: 수료증, 계약서)을 받아. 그리고 우리는 그 위에 동적으로 바뀔 내용(이름, 날짜 등)만 PHP로 찍어내는 거지.

`certificate-template.pdf` 파일이 있고, '수료자 이름'과 '날짜'를 넣어야 한다고 가정해보자.

<?php
require_once __DIR__ . '/vendor/autoload.php';

// 한글 폰트 설정 (템플릿 위에 쓸 글자가 한글일 경우)
$defaultConfig = (new Mpdf\Config\ConfigVariables())->getDefaults();
$fontDirs = $defaultConfig['fontDir'];
$defaultFontConfig = (new Mpdf\Config\FontVariables())->getDefaults();
$fontData = $defaultFontConfig['fontdata'];

$mpdf = new \Mpdf\Mpdf([
    'fontDir' => array_merge($fontDirs, [__DIR__ . '/fonts']),
    'fontdata' => $fontData + ['notosanskr' => ['R' => 'NotoSansKR-Regular.ttf']],
    'default_font' => 'notosanskr'
]);

// 1. 템플릿 PDF 파일 불러오기
$pageCount = $mpdf->setSourceFile('certificate-template.pdf');
$templateId = $mpdf->importPage(1); // 첫 번째 페이지만 사용

// 2. 템플릿을 배경으로 사용
// useTemplate()은 템플릿을 가져와서 현재 페이지에 배치하는 역할을 합니다.
// 세 번째 인자로 페이지 크기를 자동으로 조절할지 여부를 설정할 수 있습니다.
$mpdf->useTemplate($templateId, null, null, null, null, true);

// 3. 템플릿 위에 글자 쓰기
// WriteText() 메소드는 좌표(x, y)를 기반으로 텍스트를 씁니다.
// 이 좌표는 포토샵이나 PDF 편집 툴로 미리 알아내야 합니다. (단위: mm)
$mpdf->WriteText(85, 120, '홍길동'); // x: 85mm, y: 120mm 위치에 이름 쓰기
$mpdf->WriteText(105, 155, date('Y년 m월 d일')); // 날짜 쓰기

$mpdf->Output('completed-certificate.pdf', 'D');
?>

여기서는 `WriteHTML()`이 아니라 `WriteText(x, y, 'text')`를 사용했어. 마치 투명한 필름 위에 글씨를 쓰는 것과 같아. **가장 어려운 부분은 글씨를 쓸 정확한 x, y 좌표를 찾는 거야.** 이건 어쩔 수 없이 포토샵이나 Acrobat Pro 같은 툴을 열어서 눈금자로 대충 재보거나, 여러 번 값을 바꿔가며 테스트하는 수작업이 좀 필요해. 조금 귀찮지만, 한번 좌표를 찾아두면 대량의 문서를 자동으로 생성할 수 있으니 엄청나게 강력한 기능이지.

⚠️ 주의: FPDI는 PDF의 기존 내용을 '수정'하거나 '삭제'하는 게 아니야. 단지 기존 페이지를 '배경 이미지'처럼 가져와서 그 위에 새로운 내용을 '덧그리는' 방식이라는 걸 꼭 기억해줘!

💡 성능 최적화 & 실무 팁

자, 이제 PDF를 만들고 조작하는 법은 거의 다 알게 됐어. 하지만 실무에서는 '잘' 만드는 것만큼 '효율적으로' 만드는 것도 중요해. PDF 생성은 생각보다 서버 자원을 많이 먹는 작업이거든.

🔥 PDF 생성, 이것만은 지키자!

1. **캐싱, 캐싱, 또 캐싱:** 만약 PDF 내용이 자주 바뀌지 않는다면(예: 어제 자 일일 리포트), 한 번 생성한 PDF는 파일로 저장해두고 다음 요청부터는 그 파일을 바로 보여주자. 매번 똑같은 내용을 다시 생성하는 건 엄청난 서버 자원 낭비야. `file_exists()` 함수로 파일이 있는지 확인하고, 없으면 생성하고, 있으면 바로 `readfile()`로 출력하는 간단한 로직만 추가해도 서버 부하가 확 줄어들어.

2. **이미지 최적화는 필수:** PDF에 들어가는 이미지가 너무 크면 파일 용량이 기하급수적으로 커지고 생성 속도도 느려져. 포토샵이나 `imagemagick` 같은 툴로 웹에 최적화된 용량(72dpi, 적절한 크기)으로 이미지를 미리 줄여서 사용하자.

3. **복잡한 PDF는 백그라운드에서:** 수백 페이지짜리 연간 보고서처럼 생성에 몇십 초, 몇 분이 걸리는 PDF를 사용자가 요청하자마자 만들기 시작하면? 사용자는 하염없이 흰 화면만 보다가 지쳐서 떠나버릴 거야. 이런 작업은 반드시 백그라운드(Background Job)로 처리해야 해. 사용자에게는 "PDF 생성이 시작되었습니다. 완료되면 이메일로 보내드리거나, 내 문서함에서 확인하실 수 있습니다." 라고 알려주고, 실제 생성 작업은 '큐(Queue)' 시스템(예: Redis, RabbitMQ)을 통해 별도의 워커 프로세스가 처리하도록 만들어야 해.

4. **단순한 HTML이 최고:** mPDF가 똑똑하긴 하지만, 너무 복잡하고 깊게 중첩된 테이블이나 비표준적인 CSS로 가득 찬 HTML을 주면 힘들어해. 렌더링 속도가 느려지거나 메모리 부족 오류가 날 수 있어. PDF로 만들 HTML은 최대한 단순하고 깨끗하게 유지하는 게 좋아.

5. **서버 설정 확인:** 대용량 PDF를 다루다 보면 `memory_limit` (메모리 사용량 제한)이나 `max_execution_time` (스크립트 최대 실행 시간) 초과 오류를 만날 수 있어. `php.ini` 파일에서 이 값들을 적절히 늘려줘야 할 수도 있지만, 이건 최후의 수단이야. 그 전에 코드 레벨에서 최적화를 먼저 시도하는 게 올바른 순서야.

🎉 마무리하며: 이제 당신도 PDF 마스터!

와, 정말 긴 여정이었어! 여기까지 스크롤을 내린 너 자신에게 박수를 보내 줘. 👏

우리는 오늘 PHP로 PDF를 다루는 거의 모든 것을 훑어봤어. 왜 PDF를 써야 하는지부터 시작해서, mPDF라는 강력한 무기를 사용해 HTML을 멋진 PDF 문서로 변환하는 법, 한글 폰트를 적용하고, 헤더와 푸터를 다는 디테일까지. 심지어 FPDI를 이용해 기존 PDF를 합치거나 템플릿으로 활용하는 고급 기술까지 맛봤지.

이제 "PDF로 만들어주세요"라는 요구사항은 더 이상 두려운 존재가 아닐 거야. 오히려 "어떤 디자인으로 만들어 드릴까요?"라고 자신 있게 되물을 수 있는, 든든한 기술 스택 하나를 완벽하게 장착한 셈이지.

물론 오늘 배운 게 전부는 아니야. 각 라이브러리에는 우리가 다루지 못한 수많은 옵션과 기능들이 숨어있어. 개발의 세계는 끝없는 탐험과도 같으니까, 막히는 부분이 생기면 주저하지 말고 공식 문서를 찾아보고 여러 가지 실험을 해보는 용기를 잃지 않았으면 해.

만약 이 모든 과정이 너무 복잡하게 느껴지거나, 당장 프로젝트에 적용하기에 시간이 부족하다면, 재능넷 같은 전문가 플랫폼에서 PHP PDF 전문가의 도움을 받아보는 것도 아주 현명한 방법이야. 다른 사람의 경험과 노하우를 활용해서 시간을 아끼고 더 높은 퀄리티의 결과물을 얻는 것도 뛰어난 개발자의 역량 중 하나거든.

자, 이제 배운 것들을 네 프로젝트에 직접 적용해볼 시간이야. 멋진 인보이스, 깔끔한 리포트, 세상에 하나뿐인 수료증을 너의 코드로 직접 만들어봐. 그 과정에서 느끼는 성취감은 분명 코딩의 또 다른 즐거움이 될 거야. 파이팅!

댓글 작성

이 글에 대한 여러분의 생각을 들려주세요

댓글 0
댓글을 불러오는 중입니다.

아직 댓글이 없습니다.