CodeIgniter API 참조

한눈에 보기

CodeIgniter 패키지는 컨트롤러 중심의 간결한 API 표면을 제공합니다. 하나의 문서를 감싸는 Pdf 라이브러리 래퍼(Services::pdf() 및 전역 pdf() 헬퍼), 빌드된 문서를 DownloadResponse(PdfResponse)로 변환하는 응답 헬퍼, 그 뒤를 받치는 Services 팩토리(글꼴/이미지 레지스트리, 문서 팩토리, 선택적 서명자 및 TSA 클라이언트), NextPdf 구성 클래스, 그리고 정적 빌더 콜러블로 비동기 생성을 수행하는 GeneratePdfJob으로 구성됩니다.

여기서 시작하십시오. 컨트롤러에서 Services::pdf()(또는 pdf() 헬퍼)를 호출하고, $pdf->document()에 콘텐츠를 추가한 다음, $pdf->download('file.pdf')를 반환합니다. 이 경로 하나로 가장 일반적인 작업을 처리할 수 있습니다. 아래 참조 표는 표면별로 구성되어 있으며, 일반 작업 섹션에서 실행 가능한 형태를 먼저 보여 줍니다.

일반 작업

실무에서 가장 자주 사용하는 흐름입니다. 각 샘플은 nextpdf/codeigniter를 기준으로 소스와 대조해 검증했습니다.

컨트롤러에서 다운로드 가능한 PDF를 반환합니다 — 표준 렌더링 경로입니다.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

동작 방식: 새 Document를 감싼 새 Pdf를 확인하고, 셀 하나를 작성한 다음, DownloadResponse 처리(disposition)와 패키지 보안 헤더가 적용된 attachment를 반환합니다.

브라우저에서 PDF를 인라인으로 미리 봅니다 — 동일한 래퍼에서 download() 대신 inline()을 사용합니다.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

동작 방식: 전역 pdf() 헬퍼(Services::pdf()와 동일)를 사용하며, 브라우저가 PDF를 다운로드하지 않고 표시하도록 DownloadResponse 처리(disposition)가 적용된 inline을 반환합니다.

큐에서 PDF를 비동기적으로 생성합니다 — 정적 빌더와 함께 GeneratePdfJob을 푸시합니다.

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

동작 방식: 생성 작업을 큐에 넣습니다. 워커는 빌더(App\PdfBuilders\...::method 정적 콜러블이어야 함)와 출력 경로(WRITEPATH/pdfs/ 아래로 해석되고 .pdf로 끝나야 함)를 검증한 뒤, 새 문서를 빌드하여 저장합니다.

라이브러리 래퍼

Pdf 래퍼가 있고 응답 또는 저장 메서드가 필요할 때 이 표를 참조하십시오.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 원인	참고
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: 새 코어 문서입니다.	제공된 문서를 한 번의 응답 또는 저장 작업에 사용할 수 있도록 감쌉니다.	`Pdf`	예상되는 예외 없음.	출력 후에는 래퍼를 재사용하지 마십시오.
`Pdf::document()`	없음.	감싼 문서를 반환합니다.	`NextPDF\Core\Document`	예상되는 예외 없음.	코어 작성 API를 호출할 때 사용합니다.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: 응답 파일 이름입니다.	브라우저 인라인 처리(disposition)를 설정합니다.	`CodeIgniter\HTTP\DownloadResponse`	코어 직렬화 오류입니다.	다음에 위임합니다: `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: 응답 파일 이름입니다.	브라우저 첨부 처리(disposition)를 설정합니다.	`DownloadResponse`	코어 직렬화 오류입니다.	다음에 위임합니다: `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: 응답 파일 이름입니다.	다른 프레임워크 패키지와 API가 동등하도록 제공합니다.	`DownloadResponse`	코어 직렬화 오류입니다.	CodeIgniter가 바이너리 출력을 기본적으로 처리합니다.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: 응답 파일 이름입니다.	다른 프레임워크 패키지와 API가 동등하도록 제공합니다.	`DownloadResponse`	코어 직렬화 오류입니다.	스트리밍되지 않는 응답과 동일한 크기 제어를 사용합니다.
`Pdf::save(string $path)`	`path`: 파일 시스템 대상입니다.	감싼 문서를 파일에 기록합니다.	`void`	파일 시스템 또는 코어 쓰기 오류입니다.	저장하기 전에 스토리지 루트를 검증하십시오.

서비스 및 헬퍼

특정 서비스 팩토리 또는 전역 헬퍼 함수가 필요하고, 공유 동작과 반환 타입을 확인해야 할 때 이 표를 참조하십시오.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 원인	참고
`Services::fontRegistry(bool $getShared = true)`	`getShared`: CodeIgniter 공유 서비스 플래그입니다.	구성된 글꼴로 예열된 뒤 잠기는 공유 레지스트리입니다.	`FontRegistryInterface`	`RuntimeException`. 누락된 확장 또는 안전하지 않은 글꼴 경로에서 발생합니다.	`fontsPath`에서 스트림 래퍼와 널 바이트를 거부합니다.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: 공유 서비스 플래그입니다.	크기가 제한된 공유 LRU 이미지 레지스트리입니다.	`ImageRegistry`	예상되는 예외 없음.	캐시 크기는 `imageCacheMb`로 제어됩니다.
`Services::documentFactory(bool $getShared = true)`	`getShared`: 공유 서비스 플래그입니다.	공유 레지스트리를 사용하는 공유 팩토리입니다.	`DocumentFactoryInterface`	레지스트리 설정 오류입니다.	팩토리는 재사용할 수 있지만 문서는 그렇지 않습니다.
`Services::tsaClient(bool $getShared = true)`	`getShared`: 공유 서비스 플래그입니다.	`tsa.url`이 비어 있으면 `null`을 반환합니다.	`TsaClient	null`	HTTP 클라이언트 또는 TSA 구성 오류입니다.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: 공유 서비스 플래그입니다.	서명이 비활성화되어 있으면 `null`을 반환합니다.	`SignerInterface	null`	인증서 또는 서명 수준 오류입니다.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: 공유 서비스 플래그입니다.	새 문서를 생성하고, 기본값을 적용하며, 선택적으로 PDF/A 또는 Artisan을 구성합니다.	`Document`	선택적 확장 또는 문서 구성 오류입니다.	요청 안전성을 위해 기본값 `false`를 유지하십시오.
`Services::pdf(bool $getShared = false)`	`getShared`: 공유 서비스 플래그입니다.	새 문서를 중심으로 새 `Pdf` 래퍼를 생성합니다.	`NextPDF\CodeIgniter\Libraries\Pdf`	문서 설정 오류입니다.	컨트롤러에서 주로 사용하는 서비스입니다.
`Services::eInvoiceEmbedder()`	없음.	Premium Pro 전자 인보이스 임베더 클래스가 없으면 `null`을 반환합니다.	`EmbedderInterface	null`	선택적 패키지 생성 오류입니다.
`Services::eInvoiceValidator()`	없음.	Premium Enterprise 검증기 클래스가 없으면 `null`을 반환합니다.	`ValidatorInterface	null`	선택적 패키지 생성 오류입니다.
`Services::eInvoiceProfile()`	없음.	Premium Pro가 설치된 경우 EN16931 프로필을 반환합니다.	`ProfileInterface	null`	선택적 패키지 오류입니다.
`Services::schematronRunner()`	없음.	Premium Enterprise Schematron 검증기가 없으면 `null`을 반환합니다.	`SchematronRunnerInterface	null`	선택적 패키지 생성 오류입니다.
`Registrar::Autoload()`	없음.	CodeIgniter 자동 로드 구성에 패키지 헬퍼를 추가합니다.	`array`	예상되는 항목 없음.	모듈이 로드되면 `pdf()`와(과) `pdf_document()`을(를) 활성화합니다.
`pdf()`	없음.	`Services::pdf(false)`를 호출합니다.	`Pdf`	문서 설정 오류입니다.	컨트롤러를 위한 편의 헬퍼입니다.
`pdf_document()`	없음.	`Services::pdfDocument(false)`를 호출합니다.	`Document`	문서 설정 오류입니다.	코어 문서 API를 선호할 때 사용하는 편의 헬퍼입니다.

HTTP 응답

이미 빌드된 Document가 있고 Pdf 래퍼를 거치지 않고 직접 DownloadResponse를 구성하려 할 때 이 표를 참조하십시오.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 원인	참고
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: 빌드된 문서, `filename`: 응답 파일 이름입니다.	파일 이름에 `.pdf` 확장자와 인라인 처리(disposition)를 보장합니다.	`DownloadResponse`	코어 직렬화 오류입니다.	PDF 콘텐츠 타입과 방어적 헤더를 추가합니다.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	`inline`과 동일합니다. 처리(disposition)는 첨부입니다.	파일 이름에 `.pdf` 확장자를 보장합니다.	`DownloadResponse`	`inline`과 동일합니다.	브라우저 다운로드에 사용합니다.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	`inline`과 동일합니다.	CI4에서 `inline`과 동일하게 동작합니다.	`DownloadResponse`	`inline`과 동일합니다.	프레임워크 간 API 동등성을 위해 제공됩니다.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	`download`와 동일합니다.	CI4에서 `download`와 동일하게 동작합니다.	`DownloadResponse`	`download`와 동일합니다.	프레임워크 간 API 동등성을 위해 제공됩니다.

큐 작업

비동기 생성을 연결할 때 정확한 작업 데이터 키와 빌더 콜러블 계약을 확인해야 하면 이 표를 참조하십시오.

기호	매개변수	기본 동작	반환값	예외 발생 또는 실패 원인	참고
`GeneratePdfJob::process()`	작업 데이터 키: `builder`, `outputPath`, 선택적 `context`.	생략하면 빈 컨텍스트 배열을 사용합니다.	`void`	`InvalidArgumentException`. 안전하지 않은 빌더 또는 출력 경로에서 발생하며, 코어 쓰기 오류도 발생할 수 있습니다.	빌더는 `App\PdfBuilders\...\*::method`여야 합니다.
빌더 콜러블	`Document $doc`, `array $context`.	작업 데이터 외에는 기본 컨텍스트가 없습니다.	`Document`	빌더에서 발생시키는 예외입니다.	CI4 큐 페이로드는 직렬화된 데이터이므로 정적 콜러블이 필요합니다.

구성

페이지 형식, 경로, 서명, TSA 또는 문서 메타데이터의 기본값을 NextPdf 구성 클래스에서 변경할 때 이 표를 참조하십시오.

속성	타입	기본 동작	참고
`pageFormat`	`string`	`A4`.	기본 페이지 형식입니다.
`orientation`	`string`	`P`.	기본 방향입니다.
`unit`	`string`	`mm`.	기본 단위입니다.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'`와 `WRITEPATH . 'cache/nextpdf'`입니다.	경로는 애플리케이션이 제어하는 스토리지 내부에 유지하십시오.
`signature`	`array`	레벨 `B-B`(으)로 비활성화됩니다.	인증서, 키, 비밀번호, 추가 인증서 및 레벨입니다.
`tsa`	`array`	URL이 `null`일 때 비활성화되며, 시간 제한은 30 초입니다.	자격 증명, mTLS 파일, 공개 키 핀 및 HTTP 정책입니다.
`ocspCache`	`array`	86400 초 TTL로 활성화됩니다.	사용 가능한 경우 서명 검증 흐름에서 사용됩니다.
`preloadFonts`	`list<string>`	비어 있습니다.	레지스트리가 잠기기 전에 예열됩니다.
`imageCacheMb`	`int`	`50`.	프로세스 수명 이미지 캐시를 제어합니다.
`fontCacheLocking`	`bool`	`true`.	글꼴 레지스트리 변경을 요청 처리에서 분리합니다.
`artisan`	`array`	구성하고 설치한 경우가 아니면 Chrome 렌더러는 비활성화됩니다.	`ChromeRendererConfig::fromArray()`에 매핑됩니다.
`defaults`	`array`	작성자(creator)는 `NextPDF`, 저자는 비어 있음, 언어는 `en`, 기본 여백과 글꼴입니다.	`Services::pdfDocument()`는 `creator`, `language`, 그리고 (비어 있지 않을 때) `author`만 적용합니다. `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` 및 `bleed_box` 키는 정의된 기본값이지만 현재 적용하지 않습니다.

개발 참고 사항

GeneratePdfJob은 출력을 WRITEPATH . 'pdfs'로 제한하고 .pdf를 요구합니다.
App\PdfBuilders 외부의 빌더 콜러블은 수정된 큐 페이로드로 임의 코드가 실행되는 것을 방지하기 위해 거부됩니다.
컨트롤러 흐름에서는 service('pdf') 또는 패키지 헬퍼를 사용하고, 장시간 실행되는 생성에는 큐 작업을 사용하십시오.