Artisan 빠른 시작

한눈에 보기

먼저 ChromeRendererConfig를 NextPDF 문서에 설정하고 writeHtmlChrome()을 호출한 후 저장합니다. Chrome이 HTML을 렌더링하고 브리지가 그 결과를 Form XObject로 가져오며, 텍스트는 선택 가능한 상태로 유지됩니다.

개념 개요

writeHtmlChrome()은 NextPDF 코어 Document의 메서드이며, HasTextOutput concern에서 제공합니다. 이 메서드는 입력을 검증하고 Artisan 렌더러를 확인한 뒤 HTML을 Chrome으로 전송합니다. 그런 다음 반환된 PDF를 파싱해 0번 페이지를 현재 커서 위치에 Form XObject로 임베드합니다. 공개 시그니처는 writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static이며, nextpdf/coresrc/Core/Concerns/HasTextOutput.php에 대해 검증되었습니다.

코드 예제 — 빠른 시작

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

이는 패키지 README.md에 제시된 표준 흐름입니다. Chrome이 flex 레이아웃을 처리합니다. 페이지가 래스터 이미지가 아니라 Form XObject로 임베드되므로 출력물의 숫자는 선택 가능한 텍스트로 유지됩니다.

사용자 지정 페이지 크기

고정된 페이지 크기에 맞추려면 너비와 높이를 PDF 포인트 단위로 명시적으로 전달합니다(A4 예시):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

둘 다 제공하면 Chrome이 해당 용지 크기에 맞춰 정확히 인쇄합니다. 높이를 생략하거나 null을 전달하면 브리지가 측정된 콘텐츠 높이에 자동으로 맞추고 작은 리플로우 안전 버퍼를 추가합니다. 이 버퍼가 필요한 이유와 재정의해야 하는 시점은 /integrations/artisan/production-usage/를 참조하십시오.

제공되는 기능

속성	동작
텍스트	선택 및 검색 가능(래스터화되지 않은 벡터 텍스트)
CSS	Chrome 레이아웃 — flexbox, grid, 복잡한 선택자, data URI를 통한 웹 글꼴
네트워크	하위 리소스를 가져오지 않습니다. 원격 URL은 로드되지 않습니다(/integrations/artisan/security-and-operations/ 참조).
페이지	Chrome 출력의 0번 페이지를 가져옵니다

엣지 케이스 및 주의 사항

빈 HTML은 아무 동작도 하지 않습니다. writeHtmlChrome('')은 문서를 변경하지 않고 반환합니다(HasTextOutput::writeHtmlChrome에서 검증됨).
페이지가 아직 없는 경우. 페이지가 존재하지 않으면 writeHtmlChrome()이 렌더링 전에 하나를 추가합니다.
원격 자산은 로드되지 않습니다. <img src="https://...">은 비어 있는 상태로 렌더링됩니다. 자산을 data: URI로 인라인 처리하십시오. 이는 버그가 아니라 네트워크 격리 정책입니다. /integrations/artisan/security-and-operations/를 참조하십시오.
브리지가 없는 경우. nextpdf/artisan이 설치되어 있지 않으면 코어가 치명적 오류 대신 레이아웃 예외를 발생시킵니다.

성능

첫 번째 호출에서는 Chrome 시작 및 레이아웃 비용이 발생합니다. 이후 호출은 BrowserPool을 통해 실행 중인 Chrome 프로세스를 재사용합니다. 배치 작업이나 장시간 실행되는 워커에서는 /integrations/artisan/production-usage/ 페이지의 수명 주기 및 리소스 지침을 참조하십시오.

보안 참고 사항

이 빠른 시작은 신뢰할 수 있는 하드코딩된 HTML을 사용합니다. 사용자의 영향을 받을 수 있는 HTML을 writeHtmlChrome()에 전달하기 전에 /integrations/artisan/security-and-operations/를 읽어 보십시오. 브리지는 네트워크 접근을 격리하지만 HTML 렌더링에는 여전히 위협 표면이 존재합니다.

상업적 맥락

이는 오픈 소스 브리지를 사용해 HTML에서 PDF를 생성합니다. 호환되는 전자 인보이스 XML을 동일한 문서에 임베드해야 하는 경우 Premium Pro 등급에서 임베더를 제공합니다. Premium이 없어도 오픈 소스 경로에는 영향이 없습니다.

참고 항목

/integrations/artisan/install/ — 설치
/integrations/artisan/configuration/ — 구성
/integrations/artisan/production-usage/ — 프로덕션 사용
/integrations/artisan/troubleshooting/ — 문제 해결
/integrations/artisan/security-and-operations/ — 보안 및 운영