CodeIgniter 4에서 NextPDF 문제 해결

한눈에 보기

아래의 각 증상은 패키지 또는 프레임워크 소스에서 검증된 원인을 가리킵니다. 각 항목에는 구체적인 해결 방법도 함께 제시되어 있습니다.

검색 및 해석

`Services::pdfDocument()`가 반환하는 `null`

서비스를 해석할 때 CodeIgniter는 검색된 Config\Services 클래스에서 일치하는 메서드를 찾습니다. null 반환은 프레임워크가 패키지의 Services 클래스를 전혀 검색하지 못했다는 의미입니다.

원인과 해결 방법은 다음과 같습니다.

자동 검색이 비활성화되어 있습니다. 호스트 애플리케이션이 Config\Modules::$discoverInComposer = false로 설정되어 있을 수 있습니다. 이 경우 nextpdf/codeigniter를 $composerPackages['only']에 추가하십시오. 검색은 이 플래그가 true일 때만 Composer 패키지를 대상으로 합니다.
오토로더가 오래되었습니다. Composer는 네임스페이스 접두사 NextPDF\CodeIgniter\를 해당 기본 디렉터리에 매핑합니다. 오래된 클래스맵은 클래스를 숨깁니다(PSR-4 §x1.x3). composer dump-autoload를 실행하십시오.
$aliases 목록이 잘렸습니다. 검색은 Config\Modules::$aliases의 항목에 대해서만 실행됩니다. 패키지에는 services가 필요하고 헬퍼에는 registrars가 필요합니다. 두 항목을 모두 복원하십시오.

`pdf()` 또는 `pdf_document()`가 정의되지 않음

헬퍼는 두 경로를 통해 등록됩니다. 패키지 Composer files 오토로드 항목과 패키지 Registrar입니다. 함수가 정의되지 않았다는 오류는 files 항목이 로드되지 않았음을 의미합니다.

명령 composer dump-autoload를 실행하여 files 오토로드 목록을 다시 빌드하십시오.
패키지 nextpdf/codeigniter가 vendor/composer/autoload_files.php에 나타나는지 확인하십시오.
해결 방법으로 Services::pdf(false) 또는 Services::pdfDocument(false)를 직접 호출하십시오. 헬퍼는 이러한 호출을 감싸는 가벼운 래퍼입니다.

구성

`.env` 재정의가 무시됨

재정의를 해석할 때 BaseConfig는 소문자로 변환한 짧은 클래스 이름을 접두사로 사용합니다. 클래스는 NextPdf이므로 접두사는 nextpdf입니다. nextPdf가 아니며, NextPdf도 아닙니다.

설정 nextpdf.fontsPath를 사용하고 nextPdf.fontsPath는 사용하지 마십시오.
중첩된 키는 점으로 지정합니다. nextpdf.signature.certificate.
정규화된 형식 NextPDF\CodeIgniter\Config\NextPdf.fontsPath도 작동합니다.

전체 구성 배열이 기본값으로 되돌아감

사용자가 NextPdf 클래스를 확장하고 부분 배열을 할당하면 전체 배열이 대체됩니다. 따라서 재정의하는 배열의 모든 키를 제공하십시오. 전체 배열 예제는 /integrations/codeigniter/configuration/을 참조하십시오.

런타임 오류

`RuntimeException: NextPDF requires the ext-… PHP extension`

글꼴 레지스트리는 프로세스당 한 번 mbstring과 zlib를 검증합니다. 누락된 확장 이름과 함께 이 오류를 발생시킵니다. 런타임 PHP에 표시된 확장을 설치하거나 활성화하십시오. 그런 다음 워커 또는 PHP-FPM 풀을 다시 시작하십시오.

`RuntimeException: NextPdf fontsPath contains invalid characters`

글꼴 레지스트리는 fontsPath에 스트림 래퍼(://)나 널 바이트가 포함되어 있으면 이를 거부합니다. fontsPath를 일반 파일 시스템 경로로 설정하십시오. php://, phar:// 또는 이와 유사하게 래핑된 경로를 가리키지 마십시오.

응답 문제

다운로드에서 파일 이름이 잘못 보임

PdfResponse는 파일 이름을 정규화합니다. 검증된 동작은 다음과 같습니다.

비어 있거나 공백만 있는 파일 이름은 document.pdf가 됩니다.
이름에 .pdf(또는 .PDF) 확장자가 없으면 .pdf가 추가됩니다. 기존 .PDF는 그대로 유지됩니다.
ASCII가 아닌 이름은 ASCII 폴백 및 RFC 5987 filename*=UTF-8''… 매개변수를 생성하므로, 최신 브라우저에서는 원래 이름이 표시됩니다. 이는 예상된 동작이며 버그가 아닙니다.
경로 구분 기호, 널 바이트, CR/LF는 제거됩니다.

응답에 보안 헤더가 누락됨

모든 PdfResponse 응답에는 X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag, Referrer-Policy가 포함됩니다. 클라이언트에서 이 헤더가 보이지 않는다면, 프록시 또는 애플리케이션이 다운스트림에서 헤더를 제거하거나 덮어쓰고 있는 것입니다. 리버스 프록시 전후의 응답을 모두 검사하십시오.

큐

`QueueException` — 작업을 푸시할 때 발생

큐는 푸시된 작업 이름을 Config\Queue::$jobHandlers의 키와 대조하여 확인하며, 등록되지 않은 이름은 모두 거부합니다. 작업을 이름 키로 등록한 뒤 해당 이름을 푸시하십시오.

public array $jobHandlers = ['generate-pdf' => GeneratePdfJob::class];

// dispatch
\service('queue')->push('pdf-queue', 'generate-pdf', [...]);

작업 이름으로 GeneratePdfJob::class를 푸시하면 실패합니다. 두 번째 인수는 클래스 문자열이 아니라 이름 키입니다.

`InvalidArgumentException` — 작업에서 발생

작업은 어떤 처리를 수행하기 전에 페이로드를 검증합니다. 검증된 거부 사례와 해당 메시지는 다음과 같습니다.

원인	메시지 조각
`builder`가 누락되었거나, 비어 있거나, 문자열이 아님	`non-empty static callable string`
`builder`가 벗어난 `App\PdfBuilders`	`not allowed`
`builder`가 패턴과 일치하지만 호출할 수 없음	`not a valid callable`
`outputPath`가 누락되었거나 비어 있음	`non-empty string`
`outputPath`가 벗어난 `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath`가 끝나지 않는 `.pdf`	`must end with .pdf`

빌더가 App\PdfBuilders\<Class>::<method> 정적 호출 가능 항목이 되도록 페이로드를 수정하십시오. 출력 경로가 WRITEPATH/pdfs/ 내부에서 .pdf 확장자로 해석되는지 확인하십시오.

`class … BaseJob not found`

codeigniter4/queue는 패키지의 개발 전용 종속성입니다. 워커를 실행하는 애플리케이션은 이를 직접 require해야 합니다.

composer require codeigniter4/queue

진단

composer show nextpdf/codeigniter — 패키지가 해석되는지 확인합니다.
composer dump-autoload — 검색 및 헬퍼 오토로드를 다시 빌드합니다.
php spark routes — PDF 라우트가 등록되었는지 확인합니다.
가장 빠른 검색 확인 방법은 Services::pdfDocument(false)를 호출하고 결과가 Document인지 단언하는 컨트롤러입니다.

준수

클래스-경로 매핑 — 검색 실패와 관련됨(PSR-4 Autoloader §x1.x3).

참고 항목

/integrations/codeigniter/install/ — 검색 요구 사항.
/integrations/codeigniter/configuration/ — .env 접두사 및 배열 재정의 규칙.
/integrations/codeigniter/production-usage/ — 올바른 큐 등록.
/integrations/codeigniter/boot-and-discovery/ — 검색 시퀀스.

CodeIgniter 4에서 NextPDF 문제 해결

한눈에 보기

검색 및 해석

Services::pdfDocument()가 반환하는 null

pdf() 또는 pdf_document()가 정의되지 않음

구성

.env 재정의가 무시됨