NextPDF Symfony 부팅과 탐색

한눈에 보기

커널은 NextPdfBundle을 등록합니다. 번들의 DI 확장은 services.php를 로드하고 구성 트리를 컨테이너 매개변수로 해석합니다. 그다음 단일 컴파일러 패스가 선택적 확장 기능과 글꼴 워밍업을 연결합니다.

Symfony Flex가 번들을 인식하는 방식

번들 composer.json은 자동 등록 힌트를 선언합니다.

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

Symfony Flex 애플리케이션에서는 NextPDF\Symfony\NextPdfBundle이 모든 환경용으로 config/bundles.php에 추가됩니다(all). Flex가 없으면 config/bundles.php에 번들을 수동으로 추가하십시오. Symfony는 번들 등록 모델을 공식 문서에 설명합니다(https://symfony.com/doc/current/bundles.html). 번들 클래스는 PSR-4 접두사 NextPDF\Symfony\ 아래에서 자동 로드되며, src/Symfony/에 매핑됩니다. PSR-4 오토로더는 네임스페이스 접두사를 해당 기본 디렉터리에 매핑합니다(PSR-4 §2).

부팅 시퀀스

번들 소스에서 확인한 부팅 시퀀스는 다음과 같습니다.

커널이 번들을 등록합니다. Kernel::registerBundles()은 config/bundles.php를 읽고 NextPDF\Symfony\NextPdfBundle을 인스턴스화하며, 이는 Symfony\Component\HttpKernel\Bundle\Bundle을 확장합니다.
번들을 빌드합니다. NextPdfBundle::build()은 부모 구현을 호출한 다음 하나의 컴파일러 패스 OptionalExtensionPass를 등록합니다. NextPdfBundle::getPath()은 패키지 루트를 반환합니다.
확장을 로드합니다. DI 확장 NextPDF\Symfony\DependencyInjection\NextPdfExtension(별칭 nextpdf)은 Configuration을 대상으로 processConfiguration()을 실행합니다. 그 결과 해석된 값을 nextpdf.* 컨테이너 매개변수로 설정한 다음, PhpFileLoader를 통해 config/services.php를 로드합니다.
필수 확장 가드. NextPdfExtension::load()은 ext-mbstring과 ext-zlib가 존재하는지 단언하며 마무리되고, 그렇지 않으면 즉시 실패합니다.
컴파일러 패스를 실행합니다. 컨테이너 컴파일 중에 OptionalExtensionPass::process()은 PdfFactory에 확장 가용성 플래그를 구성하고, 조건부로 서명자와 TSA 클라이언트를 등록하며, 글꼴 레지스트리 워밍업과 잠금을 예약합니다.
컨테이너 컴파일 및 캐시. Symfony는 컴파일된 컨테이너를 기록합니다. cache:warmup은 트래픽이 발생하기 전에 이 단계를 수행합니다.

컴파일러 패스

번들은 정확히 하나의 패스 NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass를 등록하며, 이는 NextPdfBundle::build()에서 추가됩니다. 이 패스는 기본(최적화 이전) 패스 그룹에서 실행됩니다. 이 패스는 네 단계를 수행합니다. 각 단계에는 가드가 적용되어 입력이 없으면 아무 동작도 하지 않습니다.

확장 플래그 — setArtisanAvailable(...)과 setProAvailable(...) 메서드 호출을 PdfFactory 정의에 추가합니다. 이 값은 Artisan 브라우저 팩토리와 Pro PDF/A 클래스에 대한 컴파일 타임 class_exists 검사에서 가져옵니다.
서명자 등록 — nextpdf.signature가 존재하고, enabled가 true이며, 인증서가 설정된 경우, 기준 B-B 프로필에 대한 인증서 정보 팩토리와 서명자 서비스를 등록합니다.
TSA 클라이언트 — nextpdf.tsa에 URL이 있는 경우, TSA 클라이언트 서비스를 등록합니다.
글꼴 워밍업 — nextpdf.preload_fonts가 비어 있지 않은 경우, 글꼴 레지스트리 정의에 warmup()과 lock() 메서드 호출을 추가합니다.

컨테이너 바인딩

config/services.php는 서비스를 정의합니다. 문서 서비스 nextpdf.document(NextPDF\Contracts\PdfDocumentInterface 및 NextPDF\Core\Document의 별칭)는 비공유입니다. 각 해석은 새 문서를 반환하며, 이는 PSR-11에서 명시적으로 허용됩니다. 하나의 id에 대한 연속적인 get() 호출은 서로 다른 값을 반환할 수 있습니다(PSR-11 §1.1.2). 글꼴 레지스트리는 공유되며 워밍업 후 잠깁니다. 이미지 레지스트리는 공유되며 kernel.reset로 태그됩니다. 전체 표는 /integrations/symfony/configuration/에 있습니다.

구성 해석 순서

내장 기본값은 Configuration(getConfigTreeBuilder())에서 가져옵니다.
애플리케이션의 재정의는 config/packages/nextpdf.yaml에 있으며, 환경별 재정의는 config/packages/<env>/ 아래에 있습니다.
Symfony는 %kernel.*% 매개변수 자리 표시자를 해석합니다. 예를 들어 fonts_path의 기본값은 %kernel.project_dir%/resources/fonts입니다.
NextPdfExtension::load()은 병합된 결과를 nextpdf.* 컨테이너 매개변수에 기록하고, 이 매개변수는 services.php와 컴파일러 패스가 사용합니다.

잘못된 값이 있으면 1~2 단계에서 Symfony InvalidConfigurationException과 함께 실패합니다.

진단

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console cache:clear

첫 번째는 등록된 서비스를 나열합니다. 두 번째는 병합된 구성을 출력합니다. 세 번째는 컨테이너를 다시 빌드하고 컴파일 타임 확장 검사를 다시 실행합니다.

적합성

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

사양	절	reference_id (참조 ID)	주장
PSR-11	`psr_11_container#1.1.2.p3.b`		컨테이너 해석은 호출마다 다를 수 있음
PSR-4	`psr_4_autoload#x1.x2.p5`		네임스페이스 접두사에서 기본 디렉터리로의 매핑

참고 항목

/integrations/symfony/integration/ — 엔드 투 엔드 연결 참조.
/integrations/symfony/install/ — 설치 및 등록.
/integrations/symfony/configuration/ — 전체 구성 트리 및 서비스 표.
/integrations/symfony/overview/ — 기능 요약.