Symfony API 참조

한눈에 보기

Symfony 패키지는 번들 등록, 구성 트리, 새 문서 생성을 위한 주입형 팩토리, HTTP 응답 헬퍼, 비동기 생성을 위한 Messenger 타입을 제공합니다. 대부분의 애플리케이션 코드에서는 두 가지 심볼만 다룹니다. PdfFactory 서비스는 주입받아 Document를 생성할 때 사용하고, PdfResponse 헬퍼는 해당 문서를 안전한 HTTP 응답으로 변환합니다. 나머지 심볼(번들, 익스텐션, 컴파일러 패스, 구성 트리, Messenger DTO, 핸들러)은 한 번 구성하거나 프레임워크가 대신 관리하는 와이어링입니다.

여기서 시작하세요: 처음 사용하는 경우 NextPDF\Symfony\Service\PdfFactory를 주입하고, create()를 호출해 새 Document를 얻은 다음, NextPDF\Symfony\Http\PdfResponse::download()로 반환하세요. 아래 첫 번째 예제가 이 흐름을 그대로 보여줍니다.

일반 작업

가장 자주 수행하는 작업을 위한 실행 가능한 스니펫 세 개입니다. 각 스니펫은 이어지는 표에서 문서화한 검증된 심볼만 사용합니다.

컨트롤러에서 PDF 다운로드 반환 — 팩토리를 주입하고 문서를 만든 뒤 응답 헬퍼에 넘깁니다:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

동작 방식: PdfFactory::create()는 사전 구성된 새 Document를 반환합니다. PdfResponse::download()는 Content-Type: application/pdf, 첨부(attachment) 디스포지션, 번들에서 고정한 보안 헤더와 함께 문서를 전송합니다.

최대 메모리 사용량을 낮게 유지하기 위해 대용량 PDF 스트리밍 — 헬퍼를 바꿔 StreamedResponse를 반환합니다:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

동작 방식: PdfResponse::streamDownload()는 구체화된 PDF를 청크 단위로 내보내며 Content-Length를 생략합니다. 인라인 표시에는 streamInline()를 사용하세요.

비동기 생성을 위해 PDF 디스패치 — GeneratePdfMessage를 Messenger 전송 계층으로 보내 렌더링이 워커에서 실행되도록 합니다:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

동작 방식: DTO는 빌더 클래스 문자열(class-string)과 검증된 출력 경로를 전달합니다. 핸들러는 빌더를 해석하고 문서를 만든 뒤 워커에서 저장합니다. 빌더 클래스는 PdfBuilderInterface를 구현하며 서비스 로케이터에 등록됩니다(로케이터 및 워커 와이어링은 Symfony 빠른 시작을 참조하세요).

팩토리

새 문서를 생성하는 주입형 서비스의 정확한 생성자와 create() 컨트랙트가 필요할 때 이 표를 참고하세요.

심볼	매개변수	기본 동작	반환값	발생 또는 실패 사유	참고
`new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)`	`factory`: 코어 팩토리. `defaults`: 작성자(creator), 저자(author), 언어, 여백. `pdfa`: 선택적 PDF/A 프로파일. `artisanConfig`: 선택적 Chrome 렌더러 구성.	기본값은 구성된 경우에만 적용됩니다.	`PdfFactory`	컨테이너 와이어링 오류.	서비스는 `create()`가 매번 새 문서를 반환하므로 싱글턴으로 둘 수 있습니다.
`PdfFactory::create()`	없음.	작성자(creator)와 언어를 적용하고, 저자(author)는 비어 있지 않은 경우에만 적용하며, PDF/A와 Artisan 구성은 사용 가능한 경우에만 적용합니다.	`NextPDF\Core\Document`	코어 구성 오류.	요청, 명령, 메시지마다 한 번씩 사용하세요.
`PdfFactory::setArtisanAvailable(bool $available)`	`available`: 컴파일 타임 가용성 플래그.	컴파일러 패스가 활성화할 때까지 비활성화되어 있습니다.	`void`	예상되는 오류 없음.	선택적 익스텐션 컴파일러 패스가 호출하는 내부 훅입니다.
`PdfFactory::setProAvailable(bool $available)`	`available`: 컴파일 타임 가용성 플래그.	컴파일러 패스가 활성화할 때까지 비활성화되어 있습니다.	`void`	예상되는 오류 없음.	Premium 가용성을 위한 내부 훅입니다.

번들, 익스텐션, 구성

이 표는 와이어링 계층입니다. 번들을 등록하거나, nextpdf 구성 트리를 해석하거나, 선택적 익스텐션 감지를 추적할 때 참고하세요. 두 번째 표에는 구성 키 자체를 나열합니다.

심볼	매개변수	기본 동작	반환값	발생 또는 실패 사유	참고
`NextPdfBundle::build(ContainerBuilder $container)`	Symfony 컨테이너 빌더.	부모 build 메서드를 호출하고 `OptionalExtensionPass`를 등록합니다.	`void`	컴파일러 패스 등록 오류.	선택적 Artisan 및 Premium 기능 감지를 활성화합니다.
`NextPdfBundle::getPath()`	없음.	패키지 루트 경로를 반환합니다.	`string`	예상되는 오류 없음.	Symfony 번들 검색 및 리소스 로딩에서 사용됩니다.
`NextPdfExtension::load(array $configs, ContainerBuilder $container)`	사용자 구성 배열과 컨테이너 빌더.	입력된 `nextpdf` 구성을 처리하고, 해석된 매개변수를 저장하며, 서비스 정의를 로드한 뒤, 필수 익스텐션을 확인합니다.	`void`	구성 검증, 서비스 로드 또는 익스텐션 누락 오류.	필수 익스텐션은 `mbstring`과 `zlib`입니다.
`NextPdfExtension::getAlias()`	없음.	루트 구성 키로 `nextpdf`를 사용합니다.	`string`	예상되는 오류 없음.	번들은 `nextpdf:` 아래에서 구성하세요.
`Configuration::getConfigTreeBuilder()`	없음.	검증된 `nextpdf` 구성 트리를 정의합니다.	`TreeBuilder`	Symfony 구성 정의 오류.	실용적인 범위에서 Laravel 구성 형태를 따릅니다.
`OptionalExtensionPass::process(ContainerBuilder $container)`	Symfony 컨테이너 빌더.	선택적 Artisan 및 Premium 서비스를 감지하고 팩토리 가용성 플래그를 전환합니다.	`void`	컴파일러 패스 와이어링 오류.	컨테이너 컴파일 중에 실행됩니다.

구성 키	타입	기본 동작	참고
`page_format`	enum	`A4`. 허용 값에는 `A3`, `A5`, `Letter`, `Legal`, `Tabloid`가 포함됩니다.	기본 문서 생성에 적용됩니다.
`orientation`	enum	`P`. 허용되는 값은 `P`와 `L`입니다.	페이지에 다른 방향이 필요한 경우 명시적인 문서 호출을 사용하세요.
`unit`	enum	`mm`. 허용되는 값은 `pt`, `mm`, `cm`, `in`입니다.	프레임워크 기본값을 코어 단위와 일치하게 유지합니다.
`pdfa`	`string	null`	`null`. 허용되는 값은 `4`, `4e`, `4f`입니다.
`fonts_path` / `cache_path`	`string`	프로젝트 글꼴 경로와 커널 캐시 경로.	런타임 역할에 따라 두 경로를 모두 읽거나 쓸 수 있게 유지하세요.
`signature.*`	`array`	기본적으로 비활성화되며 서명 레벨은 `B-B`입니다.	인증서, 키, 비밀번호, 추가 인증서, 레벨을 제공합니다.
`tsa.*`	`array`	URL이 `null`이면 비활성화됩니다. 타임아웃 기본값은 30 초입니다.	자격 증명, mTLS 파일, 공개 키 핀, HTTP 정책을 지원합니다.
`ocsp_cache.*`	`array`	86400 초 TTL로 활성화됩니다.	사용 가능한 경우 검증 및 장기 서명 흐름에서 사용됩니다.
`messenger.*`	`array`	전송 계층은 `async`, 타임아웃은 120, 재시도는 3 회입니다.	비동기 생성 워크플로에서 사용됩니다.
`artisan.*`	`array`	구성하고 설치하지 않는 한 Chrome 렌더러는 비활성화됩니다.	선택적 렌더러를 사용할 수 있을 때 `ChromeRendererConfig`에 매핑됩니다.
`defaults.*`	`array`	작성자(creator) `NextPDF`, 저자(author) 빈 값, 언어 `en`, 기본 여백 및 글꼴.	적용은 `PdfFactory::create()`에서 수행합니다.

HTTP 응답

올바른 응답 헬퍼(인라인 표시와 다운로드, 버퍼링과 스트리밍)를 선택하고 각 헬퍼의 파일 이름 및 헤더 동작을 확인할 때 이 표를 사용하세요.

심볼	매개변수	기본 동작	반환값	발생 또는 실패 사유	참고
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: 빌드된 문서. `filename`: 응답 파일 이름.	누락된 경우 `.pdf`를 추가합니다.	`Symfony\Component\HttpFoundation\Response`	코어 직렬화 오류.	PDF 콘텐츠 타입과 방어적 헤더를 설정합니다.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	매개변수는 `inline`과 동일하며, 디스포지션은 첨부(attachment)입니다.	브라우저 다운로드 응답을 반환합니다.	`Response`	오류는 `inline`과 동일.	명시적 다운로드에 사용하세요.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	매개변수는 `inline`과 동일.	구체화된 PDF 바이트를 청크 단위로 내보냅니다.	`StreamedResponse`	오류는 `inline`과 동일.	문서 구체화 자체를 피하지는 않습니다.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	매개변수는 `streamInline`과 동일하며, 디스포지션은 첨부(attachment)입니다.	다운로드 스트림 응답.	`StreamedResponse`	오류는 `streamInline`과 동일.	렌더링 전에 출력 크기 정책을 적용하세요.

Messenger 메시지

비동기 경로(디스패치하는 메시지 DTO, 구현해야 하는 빌더 인터페이스, 워커에서 실행되는 핸들러)를 구축할 때 이 표를 참고하세요.

심볼	매개변수	기본 동작	반환값	발생 또는 실패 사유	참고
`new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])`	`builderClass`: `PdfBuilderInterface`를 구현하는 클래스 문자열(class-string). `outputPath`: 대상 `.pdf`. `builderContext`: 직렬화 가능한 데이터.	빈 컨텍스트 배열입니다.	메시지 DTO.	`InvalidArgumentException`은 잘못된 FQCN, 스트림 래퍼, 널 바이트, 경로 순회, 빈 경로 또는 `.pdf`가 아닌 대상에 대해 발생합니다.	Messenger 전송 계층은 클로저가 아니라 데이터를 전달합니다.
`PdfBuilderInterface::build(Document $document, array $context): Document`	`document`: 새로 구성된 문서. `context`: 직렬화 가능한 메시지 데이터.	메시지 값 외에 기본 컨텍스트는 없습니다.	구성된 `Document`.	빌더별 예외.	빌더를 결정론적이고 멱등하게 유지하세요.
`new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)`	PDF 팩토리와 태그된 빌더 서비스 로케이터.	생성자에서는 문서를 만들지 않습니다.	`GeneratePdfHandler`	컨테이너 와이어링 오류.	로케이터는 `PdfBuilderInterface` 구현체만 노출해야 합니다.
`GeneratePdfHandler::__invoke(GeneratePdfMessage $message)`	`message`: 검증된 메시지 DTO.	컨테이너에서 빌더를 해석하고 문서를 만든 뒤 저장합니다.	`void`	빌더 서비스 누락, 잘못된 빌더 결과, 코어 쓰기 오류.	정적 콜백보다 서비스 빌더를 선호하세요.

개발 참고 사항

절대로 Document를 서비스로 저장하지 마세요. PdfFactory를 저장하고 각 작업 단위마다 create()를 호출하세요.
직렬화 가능한 컨텍스트만 큐에 넣으세요. builderContext에 열린 스트림, 클로저 또는 요청 객체를 넣지 마세요.
배포 환경에 테넌트별 스토리지 루트가 있는 경우 출력 경로 정책을 DTO보다 엄격하게 유지하세요.