CodeIgniter 개발자 가이드

한눈에 보기

CodeIgniter 패키지는 서비스 팩토리, 헬퍼 함수, 단일 문서를 감싸는 가벼운 Pdf 라이브러리 래퍼를 제공합니다. 이 래퍼는 컨트롤러에서 편리하게 사용할 수 있습니다. CodeIgniter 큐 페이로드는 직렬화된 데이터이므로, 큐 작업에서는 정적 빌더 콜러블을 사용합니다.

컨트롤러 흐름, 서비스, 큐 빌더 또는 테스트를 nextpdf/codeigniter 기준으로 설계할 때 이 가이드를 사용하십시오.

아키텍처 경계

계층	소유 주체	책임	여기에 두면 안 되는 것
컨트롤러	애플리케이션	권한을 확인하고, 빌더 또는 서비스를 호출하고, `DownloadResponse`를 반환합니다.	공유 레이아웃 로직.
라이브러리 래퍼	`nextpdf/codeigniter`	단일 `Document`를 감싸고 response/save 헬퍼를 제공합니다.	장기 보관용 문서 저장.
서비스 팩토리	`nextpdf/codeigniter`	공유 레지스트리와 새 문서를 생성합니다.	업무별 저장소 루트.
큐 빌더	애플리케이션	정적 콜러블 입력을 기반으로 문서를 빌드합니다.	요청 객체 또는 직렬화할 수 없는 상태.
코어 엔진	`nextpdf/nextpdf`	PDF를 빌드하고 직렬화합니다.	CodeIgniter 응답 또는 큐 정책.

런타임 수명 주기

단계	동작	개발자 조치
자동 로드 등록	`Registrar::Autoload()`는 모듈의 헬퍼 로딩을 등록합니다.	CodeIgniter 구성을 통해 모듈을 로드합니다.
서비스 확인	`Services::pdf()`는 기본적으로 새 문서를 감싼 래퍼를 반환합니다.	요청마다 한 번만 확인합니다.
작성	애플리케이션 코드는 코어 문서 호출에 `Pdf::document()`를 사용합니다.	문서 빌드 코드는 서비스 또는 빌더에 둡니다.
응답	`PdfResponse`는 `DownloadResponse`를 반환합니다.	패키지가 PDF 헤더를 설정하도록 둡니다.
큐 실행	`GeneratePdfJob::process()`는 빌더와 출력 경로를 검증한 뒤 저장합니다.	큐 빌더는 `App\PdfBuilders` 아래에 둡니다.

권장 애플리케이션 구조

경로	용도
`app/PdfBuilders/*`	정적 큐 안전 빌더이며, `GeneratePdfJob`이 허용합니다.
`app/Libraries/*`	반복되는 문서 워크플로를 감싸는 선택적 애플리케이션 래퍼.
`app/Services/*`	도메인 데이터 조회 및 저장 정책.
`app/Config/NextPdf.php`	패키지 구성을 위한 애플리케이션 재정의.
`tests/app/PdfBuilders/*`	빌더 및 큐 페이로드 테스트.

간단한 흐름에는 패키지 헬퍼를 사용합니다. 문서 생성 로직이 직접 테스트해야 하는 클래스에 속할 때는 명시적 서비스 호출을 사용합니다.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

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

큐 빌더 패턴

큐 빌더는 정적이고 결정적이어야 하며 App\PdfBuilders 아래에 있어야 합니다. 컨텍스트 배열은 직렬화와 감사가 가능할 만큼 단순하게 유지합니다.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

작업은 출력 위치를 구성된 애플리케이션 PDF 디렉터리로 제한합니다. 애플리케이션에 테넌트별 저장소가 필요한 경우, 해당 정책을 하나의 서비스에 두고 큐 디스패치 전에 테스트합니다.

확장 지점

확장 지점	사용 용도	제약 조건
`Services::pdfDocument()`	문서 생성 사용자 지정.	새 문서를 반환해야 합니다.
`Services::fontRegistry()`	글꼴 워밍업 및 레지스트리 액세스.	안전하지 않은 경로를 거부하고 워밍업한 뒤 레지스트리를 잠긴 상태로 유지합니다.
`Services::pdfSigner()`	선택적 디지털 서명.	서명이 비활성화되어 있으면 `null`을 반환합니다.
`NextPDF\CodeIgniter\Libraries\Pdf`	컨트롤러용 래퍼.	래퍼 하나는 문서 하나에 매핑됩니다.
`App\PdfBuilders::*`	큐 안전 문서 빌더.	정적 콜러블 문자열이 필요합니다.
`app/Config/NextPdf.php`	애플리케이션 기본값 및 통합 설정.	프로덕션 값은 명시적으로 유지합니다.

개발 워크플로

컨트롤러는 pdf() 또는 service('pdf')를 호출해 시작합니다.
반복되는 문서 생성 로직을 app/PdfBuilders 또는 애플리케이션 서비스로 옮깁니다.
생성이 요청 경로에 비해 너무 느린 경우 GeneratePdfJob을 사용합니다.
큐 컨텍스트는 직렬화 가능하며 작게 유지합니다.
정책을 의도적으로 확장하지 않는 한 출력은 승인된 PDF 저장소 루트 아래에 저장합니다.
헬퍼, 서비스, 큐 페이로드, 안전하지 않은 경로에 대한 테스트를 추가합니다.

실패 처리

실패	처리해야 할 위치	권장 대응
누락된 확장 또는 안전하지 않은 글꼴 경로	서비스 팩토리.	서비스 확인 단계에서 빠르게 실패하게 합니다.
유효하지 않은 빌더 콜러블	큐 작업 검증.	작업을 거부하고 비밀 정보를 포함하지 않고 빌더 문자열을 로깅합니다.
안전하지 않은 출력 경로	저장소 서비스 및 큐 작업.	디스패치 전에 거부하고 작업 검증을 유지합니다.
응답 직렬화 오류	컨트롤러 또는 프레임워크 오류 처리.	부분 응답 본문을 전송하지 마십시오.
선택적 Premium 클래스를 사용할 수 없음	서비스 메서드 반환값.	선택적 e-invoice 기능을 사용하기 전에 `null`을 명시적으로 처리합니다.

안전한 기본값

관심사	기본값	재정의 시점
큐 빌더 네임스페이스	`App\PdfBuilders`.	보안 정책도 함께 업데이트하지 않는 한 기본값을 유지합니다.
출력 루트	`WRITEPATH/pdfs`.	더 강력한 허용 목록을 함께 적용할 때만 재정의합니다.
응답 파일 이름	`document.pdf`.	정제된 업무용 파일 이름을 사용합니다.
스트림 메서드	다른 프레임워크와의 API 동등성.	CodeIgniter에서 스트리밍을 메모리 경계로 간주해 의존하지 마십시오.
문서 서비스	기본적으로 새 문서.	요청 코드에서 공유 문서를 요청하지 마십시오.

테스트 체크리스트

서비스 테스트는 각 Services::pdf() 호출이 독립적인 문서를 반환하는지 검증합니다.
헬퍼 테스트는 pdf()와 pdf_document()가 새 객체를 반환하는지 검증합니다.
응답 테스트는 헤더와 파일 이름 정규화를 검증합니다.
큐 테스트는 유효하지 않은 빌더 문자열과 안전하지 않은 출력 경로를 다룹니다.
빌더 테스트는 대표적인 컨텍스트 데이터로 실행됩니다.
구성 테스트는 글꼴 경로, 캐시 경로, 서명 비활성화, TSA 비활성화 상태를 다룹니다.