NextPDF Symfony 번들 설치

한눈에 보기

Composer로 번들을 설치합니다. Symfony Flex 애플리케이션에서는 번들이 자동으로 등록됩니다. Flex가 없는 애플리케이션에서는 config/bundles.php에 한 번만 등록하면 됩니다.

요구 사항

다음 제약 조건은 번들의 composer.json에서 가져온 것입니다.

의존성	제약 조건
`php`	`>=8.4 <9.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`symfony/framework-bundle`	`^7.2`
`symfony/dependency-injection`	`^7.2`
`symfony/config`	`^7.2`
`symfony/http-foundation`	`^7.2`
`psr/log`	`^3.0`

번들은 컨테이너 빌드 시점에 PHP 확장 두 개도 추가로 검사합니다. 검사 대상 확장은 ext-mbstring와 ext-zlib입니다. 두 확장 모두 지원되는 모든 PHP 런타임에서 활성화되어 있습니다. 둘 중 하나라도 없으면 명확한 메시지와 함께 검사가 즉시 실패합니다.

선택적 패키지

다음 패키지는 번들 composer.json의 suggest 항목에 선언되어 있습니다. 설치되어 있으면 추가 동작이 활성화됩니다.

패키지	추가 기능
`nextpdf/artisan`	Chrome CDP HTML 렌더링, 컴파일 시점에 자동 감지
`nextpdf/premium`	PDF/A 아카이브 및 디지털 서명(Pro 등급 설치), 컴파일 시점에 자동 감지
`symfony/messenger`	Messenger 핸들러를 통한 비동기 PDF 생성

Composer로 설치

composer require nextpdf/symfony

번들은 PSR-4 접두사 NextPDF\Symfony\ 아래에서 자동 로드되며, src/Symfony/에 매핑됩니다. 이 매핑은 composer.jsonautoload.psr-4에 선언되어 있습니다. Composer가 생성한 자동 로더는 PSR-4 자동 로더 사양에 정의된 대로 네임스페이스 접두사를 해당 기본 디렉터리에 매핑합니다. PSR-4 §2를 참조하세요.

번들 등록

Symfony Flex(권장)

번들은 composer.json에 자동 등록 힌트를 제공합니다.

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

Flex가 활성화된 애플리케이션에서는 이 항목이 번들을 모든 환경(all)용으로 config/bundles.php에 추가합니다. 이 파일을 직접 편집할 필요는 없습니다. 등록 모델은 공식 Symfony 번들 문서(https://symfony.com/doc/current/bundles.html)를 참조하세요.

수동 등록(Flex 없음)

애플리케이션이 Symfony Flex를 사용하지 않는 경우, 번들을 config/bundles.php에 직접 추가합니다.

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

번들 클래스는 NextPDF\Symfony\NextPdfBundle입니다. 이 클래스는 Symfony의 Symfony\Component\HttpKernel\Bundle\Bundle 기본 클래스를 확장합니다. 번들의 getPath() 메서드는 패키지 루트를 반환합니다. build() 메서드는 OptionalExtensionPass 컴파일러 패스를 등록합니다.

구성 파일 제공

번들의 구성 별칭은 nextpdf입니다. config/packages/nextpdf.yaml을 만듭니다. 게시 후에는 Flex 레시피가 이 위치에 기본 사본을 자동으로 배치합니다. 제공되는 기본값에 전적으로 의존하는 최소 파일은 다음과 같습니다.

nextpdf: ~

모든 키에 기본값이 있으므로 빈 구성도 유효합니다. 전체 구성 트리는 /integrations/symfony/configuration/ 페이지에 문서화되어 있습니다.

설치 확인

컨테이너가 번들 서비스를 인식하는지 확인합니다.

php bin/console debug:container nextpdf

표시되는 서비스에는 nextpdf.document 별칭과 NextPDF\Symfony\Service\PdfFactory가 포함되어야 합니다. 최종 구성을 검사하려면 다음을 실행합니다.

php bin/console debug:config nextpdf

이 명령은 사용자 재정의 값과 기본값이 합쳐진 병합 구성 트리를 출력합니다.

엣지 케이스와 주의 사항

Core 제약 범위 — 번들은 nextpdf/core^3.0 || ^5.2를 허용합니다. Composer는 나머지 의존성 그래프를 충족하는 버전으로 해결합니다. 엔진 버전을 명확히 고정해야 한다면 애플리케이션의 composer.json에서 단일 메이저 버전을 지정하세요.
누락된 확장 검사 — php bin/console 명령이 부팅 시 ext-mbstring 또는 ext-zlib에 관한 메시지와 함께 실패하면, php.ini에서 해당 확장을 활성화하세요. 이는 번들 결함이 아니라 의도된 빠른 실패 동작입니다.
Flex가 번들을 등록하지 않은 경우 — Composer 캐시를 지우고 다시 설치하세요. Flex를 사용하지 않는 경우 수동 config/bundles.php 단계를 대신 수행하세요.

적합성

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

사양	조항	reference_id (참조 ID)	주장
PSR-4	`psr_4_autoload#x1.x2.p5`		자동 로더에서 네임스페이스 접두사를 디렉터리에 매핑