NextPDF Symfony 번들 문제 해결

한눈에 보기

대부분의 문제는 검색, 구성 검증, 컨테이너 연결, Messenger 라우팅이라는 네 가지 영역으로 나뉩니다. 아래 각 섹션에서는 증상을 번들 소스의 검증 동작과 연결한 뒤, 수정 결과를 확인할 수 있는 콘솔 명령을 제공합니다.

번들이 등록되지 않음

증상: PdfFactory가 자동 연결되지 않거나, debug:container nextpdf가 아무것도 찾지 못합니다.

원인: 번들이 config/bundles.php에 추가되지 않았습니다. Flex가 실행되지 않았거나, 애플리케이션이 Flex를 사용하지 않습니다.

해결:

php bin/console debug:container nextpdf

비어 있으면 번들을 수동으로 추가합니다:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

자동 등록 힌트는 번들 composer.json의 extra.symfony.bundles 아래에 있습니다. 이는 Flex가 활성화된 애플리케이션에만 적용됩니다.

PHP 확장이 없어 부팅에 실패함

증상: 커널이 부팅 시 RuntimeException을 발생시키며, 예외 메시지에 ext-mbstring 또는 ext-zlib가 언급됩니다.

원인: 이는 번들의 의도적인 빠른 실패(fail-fast) 가드인 NextPdfExtension::guardRequiredExtensions()입니다. 결함이 아닙니다.

해결: php.ini에서 해당 확장을 활성화하고 런타임을 다시 시작합니다. 다음 명령으로 확인합니다:

php -m | grep -E 'mbstring|zlib'

빌드 시점에 구성이 거부됨

증상: Symfony\Component\Config\Definition\Exception\InvalidConfigurationException 예외가 cache:clear 또는 cache:warmup 중에 발생합니다.

원인: 값이 스키마에서 허용하는 범위를 벗어났습니다. 이러한 제약은 Configuration.php에서 비롯됩니다:

page_format은 A4, A3, A5, Letter, Legal, Tabloid 중 하나여야 합니다.
orientation은 P 또는 L이어야 합니다.
unit은 pt, mm, cm, in 중 하나여야 합니다.
pdfa는 null, 4, 4e 또는 4f 중 하나여야 합니다.
image_cache_mb는 >= 0이어야 합니다.

해결: 병합된 구성을 출력한 다음, 문제가 되는 키를 수정합니다:

php bin/console debug:config nextpdf

PDF/A 또는 서명이 적용되지 않음

증상: pdfa 또는 signature 섹션이 설정되어 있지만 출력이 일반 PDF입니다.

원인: 이러한 기능에는 nextpdf/premium이 필요합니다. PdfFactory는 컴파일 시점에 Pro 확장이 감지된 경우에만 PDF/A를 적용합니다. 컴파일러 패스는 오직 signature.enabled가 true이고 또한 signature.certificate가 설정된 경우에만 서명자를 등록합니다.

해결: Premium이 설치되어 있고 서명자 서비스가 존재하는지 확인합니다:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Premium이 없으면 번들은 구성을 저장하지만, 설계상 이를 비활성 상태로 둡니다. Pro에서 문서화된 번들의 서명 기능은 기준 B-B 프로필입니다. NextPDF Premium 문서는 B-B를 넘어서는 프로필을 다룹니다.

Chrome 렌더링이 동작하지 않음

증상: artisan 구성이 무시됩니다.

원인: Chrome CDP 렌더링에는 nextpdf/artisan이 필요합니다. 컴파일러 패스는 컴파일 시점에 class_exists로 이를 탐지합니다. 확장이 없으면 렌더러가 연결되지 않습니다.

해결:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

이 탐지는 컨테이너 컴파일 중에 실행됩니다. 따라서 확장을 설치한 후에는 새로 cache:clear를 실행해야 합니다.

Messenger 핸들러가 호출되지 않음

증상: GeneratePdfMessage가 디스패치되지만 PDF가 기록되지 않습니다.

원인 및 해결:

메시지가 라우팅되지 않음 — NextPDF\Symfony\Message\GeneratePdfMessage를 config/packages/messenger.yaml의 전송 수단에 매핑하는 라우팅 항목을 추가한 다음, 워커(php bin/console messenger:consume <transport>)를 실행합니다.
빌더가 로케이터에 없음 — 핸들러는 클래스 문자열 ID로 PSR-11 로케이터에서 빌더를 가져옵니다. 컨테이너 식별자는 항목을 고유하게 식별하는 문자열입니다(PSR-11 §1.1.2). 로케이터에 빌더 클래스가 등록되어 있지 않으면, 핸들러는 RuntimeException을 발생시키며, 이 예외는 구성된 빌더가 PdfBuilderInterface를 구현해야 한다고 명시합니다. 빌더를 등록한 다음, 로케이터에서 이를 참조합니다.

라우팅과 로케이터를 검사합니다:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

디스패치 시 InvalidArgumentException으로 메시지가 거부됨

증상: GeneratePdfMessage를 생성할 때 InvalidArgumentException이 발생합니다.

원인: 메시지 데이터 전송 객체(DTO)가 입력을 검증합니다. 확인된 거부 규칙은 다음과 같습니다:

빈 출력 경로 또는 널 바이트를 포함하는 경로;
스트림 래퍼 스킴(예: php://...);
상위 디렉터리 .. 경로 탐색 세그먼트(POSIX 또는 Windows 구분자);
확장자 .pdf로 끝나지 않는 출력 경로(대소문자 구분 없음);
구문적으로 유효한 클래스 이름이 아닌 builderClass.

해결: .pdf로 끝나는 절대 파일 시스템 경로와 실제 정규화된 빌더 클래스 이름을 전달합니다.

문서에 오래된 데이터가 포함됨

증상: 생성된 PDF에 이전 요청의 콘텐츠가 포함됩니다.

원인: Document 인스턴스가 장기 실행 워커에서 여러 요청에 걸쳐 유지되었습니다. 문서 서비스는 바로 이런 상황을 방지하기 위해 비공유로 설계되어 있습니다.

해결: 요청 범위 메서드 내부에서 PdfFactory::create()를 호출합니다. 반환된 문서를 공유 서비스에 저장하면 안 됩니다.

진단 명령 참조

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

적합성

각 행은 이 페이지에서 제시한 규범적 주장이며, 게이트된 SDO 코퍼스의 전체 64자리 16진수 reference_id에 고정되어 있습니다. 코퍼스 매니페스트와 검색 전송을 포함하는 출처는 _sidecars/rag-citations.yaml에 있습니다.

사양	조항	reference_id 식별자	주장
PSR-11	`psr_11_container#1.1.2.p4`		컨테이너 has()/get() 식별자 계약

참고 항목

/integrations/symfony/install/ — 설치 및 등록.
/integrations/symfony/configuration/ — 전체 스키마 및 제약.
/integrations/symfony/boot-and-discovery/ — 검색 및 부팅 시퀀스.
/integrations/symfony/security-and-operations/ — 보안 헤더 및 경로 검증.