NextPDF Artisan 설치

한눈에 보기

Composer로 nextpdf/artisan을 설치합니다. 이 과정에서 함께 설치되는 chrome-php/chrome 런타임 종속성도 준비됩니다. 그런 다음 PHP 프로세스가 Chrome 또는 Chromium 바이너리에 접근할 수 있도록 설정합니다.

설치

composer require nextpdf/artisan

이 패키지는 composer.json에 다음 제약 조건을 선언합니다.

요구 사항	제약 조건	참고
php	>=8.4 <9.0	PHP 8.4 전용
nextpdf/core	^3.0 || ^5.2	오픈 소스 NextPDF 엔진
chrome-php/chrome	^1.15	전이적으로 가져오는 CDP 클라이언트 라이브러리
psr/log	^3.0	선택적으로 로거를 주입하는 지점

Composer는 chrome-php/chrome을 자동으로 해결합니다. Chrome 바이너리는 시스템 종속성이며 Composer가 설치하지 않습니다.

Chrome 바이너리 프로비저닝

이 브리지에는 실행 가능한 Chrome 또는 Chromium이 필요합니다. 기본적으로 chrome-php/chrome은 일반적인 경로에서 바이너리를 자동으로 감지합니다. 명시적인 경로로 고정하려면 구성에서 경로를 전달하십시오. 자세한 내용은 /integrations/artisan/configuration/ 및 전용 /integrations/artisan/chrome-renderer-setup/ 페이지를 참조하십시오.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

애플리케이션에 연결하기 전에 바이너리가 헤드리스로 실행되는지 확인하십시오.

chromium --headless --dump-dom about:blank

성공적으로 실행되면 빈 DOM 문서를 출력하고 0으로 종료됩니다. 0이 아닌 종료 상태는 바이너리 또는 해당 공유 라이브러리가 누락되었음을 의미합니다. 브리지가 렌더링 시점에 동일한 실패를 ChromeRenderException으로 노출하므로 계속하기 전에 이를 해결하십시오.

패키지가 연결되었는지 확인

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

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

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

이 예제는 렌더러를 생성하고 Chrome을 실행하지 않은 채 기본 HTML 보안 정책을 다시 읽어옵니다. 이를 통해 자동 로딩과 nextpdf/core 계약 바인딩이 정상적으로 확인되는지 확인할 수 있습니다. (동작은 tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected에서 검증됩니다.)

컨테이너 설치

Docker에서 Chrome 샌드박스는 추가 커널 기능 없이는 일반적으로 PID 1 / root로 시작할 수 없습니다. 이 패키지는 이런 경우에 사용할 수 있도록 noSandbox 스위치를 노출합니다. Chrome 샌드박스를 비활성화하면 실질적인 보안 비용이 따릅니다. /integrations/artisan/security-and-operations/ 페이지와 /integrations/artisan/chrome-renderer-setup/는 그 비용을 문서화하고 한계를 명시적으로 기술합니다. 해당 섹션을 읽지 않고 스위치를 설정하지 마십시오.

엣지 케이스 및 주의 사항

• chrome-php/chrome는 있지만 바이너리가 없는 경우. Composer는 성공하지만, 첫 번째 렌더링에서 실행 실패를 래핑하는 ChromeRenderException이 발생합니다. 라이브러리 확인과 바이너리 확인은 별개입니다.
• chrome-php/chrome가 없는 경우. 라이브러리가 자동 로더에서 제거되면 BrowserPool::getBrowser()는 정확한 해결 명령과 함께 ChromeNotAvailableException을 발생시킵니다. (tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable에서 검증됩니다.)
• 버전 제약 조건. nextpdf/core: ^3.0 || ^5.2 — Artisan은 두 코어 메이저 라인을 모두 지원합니다. 애플리케이션이 대상으로 하는 코어 버전을 고정하십시오.

보안 참고 사항

브리지를 설치하면 신뢰 경계에 외부 프로세스(Chrome)가 도입됩니다. 렌더링 경로를 사용자가 제공한 HTML에 노출하기 전에 /integrations/artisan/security-and-operations/를 검토하십시오.

함께 보기

• /integrations/artisan/overview/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/