Laravel API 레퍼런스

한눈에 보기

nextpdf/laravel 패키지는 프레임워크에 종속되지 않는 NextPDF 코어를 Laravel 애플리케이션에 연결합니다. 직접 호출할 수 있는 네 가지 항목을 제공합니다. 빠른 작성을 위한 Pdf 파사드, 주입 가능한 문서 생성을 위한 PdfDocumentInterface 컨테이너 바인딩, 완성된 문서를 HTTP 응답으로 변환하는 PdfResponse 헬퍼, 요청 외부에서 생성하기 위한 GeneratePdfJob 큐 작업입니다. NextPdfServiceProvider는 모든 바인딩을 등록하며 자동 검색되므로 수동 설정이 필요하지 않습니다. config/nextpdf.php 설정은 기본값, 글꼴, 큐 처리, 선택적 서명 및 TSA 기능을 제어합니다.

여기부터 시작합니다. 컨트롤러에서 곧바로 PDF를 보내려면 문서를 빌드하고 PdfResponse::download($document, 'file.pdf')를 반환합니다. 아래 첫 번째 예제를 참고합니다.

일반 작업

아래 스니펫은 가장 먼저 사용하게 될 세 가지 흐름을 다룹니다. 각 흐름은 패키지 소스를 기준으로 검증되었으며, 이어서 심볼별 전체 표가 나옵니다.

컨트롤러에서 다운로드할 수 있는 PDF 반환하기 — 가장 일반적인 작업입니다:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

동작: 새 문서를 주입받고 한 줄을 작성한 뒤, attachment 응답을 Content-Type: application/pdf 및 OWASP 보안 헤더와 함께 반환합니다. 브라우저에서 미리 보려면 대신 download()를 inline()로 교체합니다.

Pdf 파사드로 작성하고 저장하기 — 스크립트와 짧은 흐름에서 가장 빠른 경로입니다:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

동작: 파사드가 컨테이너에서 새 문서를 해결하고 셀 하나를 작성한 뒤, 완성된 PDF를 디스크에 저장합니다.

GeneratePdfJob으로 요청 스레드 외부에서 PDF 생성하기:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

동작: 워커에서 생성 작업을 큐에 넣습니다. 빌더 클로저는 컨테이너에서 해결된 문서를 받아 반환합니다. 작업은 저장하기 전에 .pdf 출력 경로를 검증합니다. 큐 이름, 타임아웃, 연결은 config('nextpdf.queue.*')에서 가져옵니다.

파사드

Pdf 파사드는 새 코어 Document를 정적으로 프록시합니다. 정적 호출 스타일이 잘 맞는 짧은 컨트롤러 흐름에서 사용합니다. 각 행은 프록시되는 문서 메서드 하나를 나타냅니다.

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
`NextPDF\Laravel\Facades\Pdf`	없음. 정적 파사드 접근자가 해결하는 대상은 `NextPDF\Contracts\PdfDocumentInterface`입니다.	Laravel이 문서 인터페이스에 대한 현재 컨테이너 바인딩을 해결합니다.	기반 코어 문서의 플루언트 API입니다.	프로바이더가 등록되지 않은 경우 Laravel 컨테이너 바인딩이 실패합니다.	짧은 컨트롤러 흐름에 사용합니다. 서비스와 작업에는 생성자 주입을 선호합니다.
`Pdf::setTitle(string $title)`	`title`: 문서 제목.	기존 제목을 모두 대체합니다.	`static`	코어 검증 또는 쓰기 시점 오류.	코어 `Document`로 프록시됩니다.
`Pdf::setAuthor(string $author)`	`author`: 문서 작성자 메타데이터.	기존 작성자를 모두 대체합니다.	`static`	코어 메타데이터 검증 오류.	애플리케이션 전역 메타데이터에는 구성된 기본값을 사용하는 것이 좋습니다.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: 선택적 페이지 크기. `orientation`: 기본값은 `Portrait`.	구성된 기본값이 생략되면 `size` 페이지 크기를 사용합니다.	`static`	코어 페이지 검증 오류.	출력 크기가 중요할 때는 명시적인 `PageSize`를 사용하는 것이 좋습니다.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	글꼴 패밀리, 스타일, 포인트 크기.	빈 스타일과 12 pt 크기입니다.	`static`	글꼴 레지스트리 또는 인코딩 오류.	지연 시간이 중요할 때는 `nextpdf.preload_fonts`를 통해 프로덕션 글꼴을 미리 로드하는 것이 좋습니다.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	셀 박스, 텍스트, 테두리 플래그, 줄바꿈 플래그, 정렬.	빈 텍스트, 테두리 없음, 줄바꿈 없음, 왼쪽 정렬.	`static`	레이아웃 또는 텍스트 인코딩 오류.	단순한 고정 레이아웃 출력에 사용합니다.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	셀 너비, 줄 높이, 텍스트, 테두리 플래그, 정렬.	테두리 없음과 왼쪽 정렬.	`static`	레이아웃 또는 텍스트 인코딩 오류.	텍스트를 고정 너비 내에서 줄바꿈해야 할 때 사용합니다.
`Pdf::writeHtml(string $html)`	`html`: HTML 조각.	현재 페이지에 렌더링하며, 필요하면 페이지를 하나 생성합니다.	`static`	코어 HTML 렌더링 오류.	신뢰할 수 없는 HTML을 수락하기 전에 입력 크기 및 리소스 정책을 적용해야 합니다.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	파일 경로와 선택적 배치 사각형.	좌표가 생략되면 코어 문서가 현재 위치와 고유 크기를 선택하도록 합니다.	`static`	이미지 디코딩, 경로 또는 레이아웃 오류.	사용자가 제공한 경로를 수락하기 전에 이미지 소스 정책을 검증해야 합니다.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: 선택적 이름. `dest`: 출력 대상.	대상이 생략되면 인라인 출력.	`string`	코어 직렬화 오류.	Laravel HTTP 응답에는 `PdfResponse`를 사용하는 것이 좋습니다.
`Pdf::save(string $path)`	`path`: 파일 시스템 대상.	완성된 PDF를 디스크에 씁니다.	`void`	파일 시스템 또는 코어 쓰기 오류.	출력 디렉터리는 애플리케이션 코드에서 검증해야 합니다.
`Pdf::getPdfData()`	없음.	PDF를 메모리로 구체화합니다.	`string`	코어 직렬화 오류.	다른 프레임워크 객체가 응답 본문을 소유해야 할 때 사용합니다.

서비스 프로바이더 및 바인딩

컨테이너 항목을 직접 해결하거나 재정의해야 할 때 이 표를 참고합니다. 예를 들어 DocumentFactoryInterface를 서비스에 주입하거나 provides()가 무엇을 지연시키는지 확인할 때입니다.

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
`NextPdfServiceProvider::register()`	없음.	`config/nextpdf.php`를 병합하고, 레지스트리, 문서 팩토리, 문서 바인딩, HTTP 클라이언트, TSA 클라이언트, 서명자, 그리고 선택적 e-인보이스 계약을 등록합니다.	`void`	기능을 사용할 때 컨테이너 또는 선택적 클래스 해결 오류가 발생할 수 있습니다.	`FontRegistryInterface`와 `ImageRegistry`는 공유됩니다. 문서는 항상 새로 생성됩니다.
`NextPdfServiceProvider::boot()`	없음.	필요한 PHP 확장을 검증하고 콘솔 모드에서 `nextpdf-config`를 게시합니다.	`void`	`RuntimeException` — 필요한 확장을 사용할 수 없는 경우.	필요한 확장은 `mbstring` 및 `zlib`입니다.
`NextPdfServiceProvider::provides()`	없음.	지연된 서비스 ID를 보고합니다.	`array<string>`	예상되는 오류는 없습니다.	다음을 포함합니다. `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface`, 그리고 `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	Laravel 컨테이너에서 해결됩니다.	`DocumentFactoryInterface`에서 일회용 `Document`를 생성한 뒤, 구성된 기본값과 선택적 PDF/A 또는 Artisan 설정을 적용합니다.	`NextPDF\Core\Document`	선택적 확장이 구성되었지만 사용할 수 없을 때 오류가 발생합니다.	요청 또는 작업마다 새 문서를 해결합니다.
`DocumentFactoryInterface`	Laravel 컨테이너에서 해결됩니다.	프로세스 수명 동안 글꼴 및 이미지 레지스트리를 공유하는 싱글톤 팩토리입니다.	`DocumentFactoryInterface`	레지스트리 설정 오류.	명시적 의존성 주입에는 이것을 사용합니다.
`SignerInterface`	Laravel 컨테이너에서 해결됩니다.	반환값은 기본적으로 `null`이며, `nextpdf.signature.enabled`와 인증서 경로가 구성된 경우는 예외입니다.	`SignerInterface	null`	인증서 로드 또는 서명 수준 검증 오류.

구성

바인딩이 읽는 런타임 대상 nextpdf.* 키를 찾을 때 이 표를 사용합니다. 환경 변수와 기본값이 포함된 키별 전체 레퍼런스는 /integrations/laravel/configuration/.에 있습니다.

키	타입	기본 동작	비고
`nextpdf.fonts_path`	`string`	생략되면 Laravel 리소스 글꼴을 사용합니다.	사용자 정의 글꼴 및 워밍업을 위한 디렉터리입니다.
`nextpdf.cache_path`	`string`	애플리케이션 캐시 경로.	PHP 워커가 쓸 수 있는 상태로 유지해야 합니다.
`nextpdf.preload_fonts`	`list<string>`	빈 목록입니다.	레지스트리 생성 중에 워밍업되며, 그 후 레지스트리는 잠깁니다.
`nextpdf.image_cache_mb`	`int`	제한된 이미지 캐시 크기입니다.	프로세스 수명 이미지 캐시 메모리를 제한합니다.
`nextpdf.defaults.*`	`array`	작성자 `NextPDF`, 언어 `en`, 선택적 작성자 및 레이아웃 기본값입니다.	각 새 문서에 적용됩니다.
`nextpdf.artisan.*`	`array`	Chrome 렌더러는 설치 및 구성되지 않는 한 비활성화됩니다.	다음에 매핑됩니다: `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	서명은 기본적으로 비활성화됩니다.	인증서, 개인 키, 비밀번호, 추가 인증서, 그리고 서명 수준.
`nextpdf.tsa.*`	`array`	URL이 비어 있으면 TSA가 비활성화됩니다.	자격 증명, mTLS 파일, 타임아웃, 공개 키 핀, 그리고 HTTP 정책을 지원합니다.
`nextpdf.ocsp_cache.*`	`array`	구성된 TTL로 OCSP 캐시가 활성화됩니다.	가능할 때 서명 검증 흐름에서 사용됩니다.

HTTP 응답

완성된 문서를 HTTP로 반환하면서 인라인 표시, 첨부 다운로드, 또는 스트리밍 출력 중에서 선택해야 할 때 이 표를 사용합니다.

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: 빌드된 문서. `filename`: Content-Disposition 파일 이름.	빈 파일 이름은 `document.pdf`로 정규화됩니다.	`Illuminate\Http\Response`	코어 직렬화 또는 응답 생성 오류.	PDF 콘텐츠 타입과 방어적 헤더를 설정합니다.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	`inline`과 동일합니다. 처리는 첨부입니다.	브라우저 다운로드 응답입니다.	`Illuminate\Http\Response`	`inline`과 동일합니다.	명시적 파일 다운로드에 사용합니다.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	`inline`과 동일합니다.	PDF 바이트를 구체화한 뒤 64 KB 청크를 내보냅니다.	`Symfony\Component\HttpFoundation\StreamedResponse`	`inline`과 동일합니다.	이는 스트리밍 HTTP 출력이며, 제로카피 렌더링이 아닙니다.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	`streamInline`과 동일합니다. 처리는 첨부입니다.	다운로드 스트림 응답입니다.	`StreamedResponse`	`streamInline`과 동일합니다.	렌더링 전에 입력 및 출력 크기 제한을 적용해야 합니다.

큐 작업

생성 작업을 요청 스레드 외부로 옮길 때 이 표를 사용합니다. GeneratePdfJob의 생성, 디스패치, 성공 또는 실패 콜백 연결을 다룹니다.

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: 대상 `.pdf`입니다. `builder`: `PdfDocumentInterface`를 받습니다. 콜백은 선택 사항입니다.	큐 이름, 타임아웃, 연결은 `config('nextpdf.queue.*')`에서 읽습니다.	작업 인스턴스입니다.	빌더 또는 콜백을 직렬화할 수 없으면 직렬화 오류가 발생합니다.	빌더는 구성된 문서를 반환해야 합니다.
`GeneratePdfJob::handle()`	없음.	지정된 `PdfDocumentInterface`를 해결하고, 빌더를 적용하고, 출력 경로를 검증한 뒤 저장합니다.	`void`	`InvalidArgumentException` — 안전하지 않은 출력 경로의 경우. 코어 쓰기 오류.	스트림 래퍼, 널 바이트, `..` 세그먼트, 그리고 `.pdf`가 아닌 경로를 거부합니다.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: 실패 원인.	구성된 실패 콜백이 있으면 호출합니다.	`void`	콜백 실패.	콜백은 멱등하게 유지해야 합니다.
`GeneratePdfJob::then(callable $callback)`	`callback`: 출력 경로를 받습니다.	성공 콜백을 대체합니다.	`self`	직렬화 가능한 클로저 오류.	디스패치 설정을 위한 플루언트 헬퍼입니다.
`GeneratePdfJob::catch(callable $callback)`	`callback`: 던져진 `Throwable`를 받습니다.	실패 콜백을 대체합니다.	`self`	직렬화 가능한 클로저 오류.	경고 또는 보상 정리에 사용합니다.

개발 노트

PdfResponse는 응답을 생성하기 전에 항상 getPdfData()를 호출합니다. 이는 지연 문서 빌더가 아닙니다.
큐 페이로드는 공유 전송 경로에서 변조될 수 있으므로, 출력 경로를 애플리케이션 소유 디렉터리로 제한해야 합니다.
요청 또는 작업마다 새 문서를 사용해야 합니다. 요청 간에 문서를 재사용하면 안 됩니다.