NextPDF 상용 에디션을 위한 ionCube Loader 설정

At a glance

일부 NextPDF 상용 배포판은 ionCube 로 인코딩된 PHP 형태로 제공되므로, 해당 코드가 실행되기 전에 PHP 런타임에 그에 맞는 ionCube Loader 가 설치되어 있어야 합니다. 이는 다음에 해당합니다.

NextPDF Pro 및 Enterprise 평가판 빌드, 그리고
NextPDF Pro 정식 (유료) 빌드.

NextPDF Enterprise 정식 제공의 경우, 패키징 방식은 계약 내용에 따라 달라집니다. 특정 런타임을 가정하지 말고 라이선스 약관에 명시된 제공 지침을 따르세요. 라이선싱 및 활성화를 참고하세요.

이 페이지는 실용적인 설정 가이드입니다. ionCube 가 무엇인지, Loader 를 설치하고 검증하는 방법, 유료 ionCube 인코딩 Pro 빌드에서 라이선스 파일이 들어가는 위치, 컨테이너에서 실행하는 방법, 그리고 흔한 실패를 해결하는 방법을 다룹니다. 지원되는 PHP 버전은 8.4 이며, 설치하는 Loader 는 해당 런타임과 정확히 일치해야 합니다.

What ionCube is and why NextPDF uses it

ionCube 는 ionCube Loader 라는 무료 런타임 구성 요소와 짝을 이루는 상용 PHP 인코더입니다. Loader 는 PHP (Zend) 확장입니다. PHP 가 시작될 때 Loader 는 인코딩된 파일을 디코딩하여 실행할 수 있게 해 줍니다. Loader 가 없으면 인코딩된 파일은 실행되지 못하며, PHP 는 대신 loader 오류를 보고합니다.

NextPDF 는 독점적인 상용 소스를 보호하면서도, 다른 Composer 패키지와 마찬가지로 배포하여 실행할 수 있는 설치 가능한 PHP 를 제공하기 위해 ionCube 인코딩을 사용합니다. 이 인코딩은 라이브러리를 호출하는 방식을 바꾸지 않습니다. 애플리케이션은 동일한 공개 계약을 대상으로 삼으며, 단지 런타임에 Loader 가 존재해야 한다는 요구 사항만 추가될 뿐입니다.

Loader 다운로드와 권위 있는 버전별 지침은 ioncube.com 의 공급업체 문서(ionCube Loader 문서 및 설치 가이드)를 이용하세요. 이 페이지는 NextPDF 고유의 설정을 다루며, Loader 자체에 대한 권위 있는 출처는 공급업체입니다.

Requirements

PHP 런타임과 모든 축에서 일치하는 ionCube Loader 를 설치하세요. 이 중 어느 하나라도 일치하지 않는 것이 가장 흔한 실패 원인입니다.

축	일치해야 하는 값
PHP version	8.4 (NextPDF 상용판은 `>=8.4 <9.0` 을 요구합니다).
Operating system	Loader 번들이 대상으로 하는 OS (Linux, Windows, macOS).
Architecture	호스트의 CPU 아키텍처로, 일반적으로 64비트(`x86-64` 또는 `aarch64`)입니다.
Thread safety	PHP 빌드와 일치하는 비스레드 안전(NTS) 또는 스레드 안전(ZTS).

Loader 외에도 다음이 필요합니다.

Composer 를 통해 설치된 NextPDF 상용 패키지 — nextpdf/pro, nextpdf/enterprise, 또는 nextpdf/premium 메타패키지.
유료 빌드의 경우, 라이선스 파일. 유료 ionCube 인코딩 Pro 빌드에 대해서는 아래 라이선스 파일 배치를 참고하세요.

현재 빌드 값을 확인하려면 php -i 를 실행하거나 phpinfo() 를 호출한 뒤 PHP Version, Architecture, Thread Safety 줄을 확인하세요. 대부분의 CLI 및 PHP-FPM 배포에서 스레드 안전은 비활성화(NTS)되어 있으며, 일부 플랫폼의 전통적인 Apache mod_php 는 ZTS 입니다. 그 정확한 값에 맞는 Loader 번들을 다운로드하세요.

Install the Loader

아래 단계는 일반적인 흐름입니다. 현재 번들의 정확한 파일 이름과 디렉터리 구성은 ioncube.com 의 ionCube Loader 문서를 따르세요.

환경(PHP 8.4, OS, 아키텍처, NTS/ZTS)에 맞는 Loader 번들을 다운로드하세요. 번들에는 PHP 버전과 스레드 안전 변형별로 하나씩의 loader 파일이 들어 있습니다.
loader 파일을 PHP 확장 디렉터리에 배치하세요. php -i 가 보고하는 extension_dir 을 사용하세요. Linux/macOS 에서 파일은 ioncube_loader_<os>_8.4.so(ZTS 빌드의 경우 ..._8.4_ts.so 사용)이며, Windows 에서는 ioncube_loader_win_8.4.dll(또는 ..._ts.dll ZTS 변형)입니다.
php.ini 에 zend_extension 으로 등록하세요. ionCube Loader 는 일반 extension 이 아니라 zend_extension 으로 로드되어야 하며, 다른 확장보다 먼저 로드되어야 합니다. loader 파일의 절대 경로를 사용하여 한 줄을 추가하세요.
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Windows 에서는 .dll 의 전체 경로를 사용하세요.
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
플랫폼에서 conf.d 형식의 include 디렉터리를 사용한다면, 이 줄을 먼저 읽히는 파일(예: 00-ioncube.ini)에 배치하여 Loader 가 다른 확장보다 먼저 초기화되도록 하세요.
PHP 런타임을 재시작하세요. PHP-FPM, 웹 서버(Apache/Nginx)를 재시작하거나, 단순히 CLI 를 다시 실행하세요 — 애플리케이션을 실행하는 대상을 재시작하면 됩니다. 장시간 실행되는 프로세스는 재시작되기 전까지 이전 구성을 유지합니다.

Verify

NextPDF 를 로드하기 전에 Loader 가 활성화되어 있는지 확인하세요.

먼저 PHP 버전 배너를 확인하세요. Loader 가 설치되면 php -v 는 이를 명시하는 줄을 추가합니다.

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

“with the ionCube PHP Loader” 라는 문구는 해당 런타임에서 Loader 가 활성화되었다는 신호입니다. 웹(FPM / mod_php) 배포의 경우 CLI 배너만으로는 충분하지 않습니다 — 그 런타임은 다른 php.ini 를 사용할 수 있습니다. 웹 서버가 제공하는 작은 스크립트로 웹 런타임을 확인하세요.

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

마지막으로, NextPDF 상용 클래스가 실제로 Composer 의 오토로더를 통해 로드되는지 확인하세요. 이는 인코딩된 코드가 처음부터 끝까지 실행됨을 증명합니다.

<?php
require __DIR__ . '/vendor/autoload.php';

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

php -v 가 Loader 를 명시하고, 웹 phpinfo() 가 ionCube 섹션을 보여 주며, 상용 클래스가 정상적으로 해석되면 Loader 가 올바르게 설정된 것입니다.

License placement (the paid, ionCube-encoded Pro build)

ionCube 는 단순한 라이선싱 모델을 사용합니다. 인코딩된 코드는 런타임에 라이선스 파일을 확인하며, 파일이 없거나 읽을 수 없거나 만료된 경우 실행을 거부합니다. 이는 유료 ionCube 인코딩 Pro 빌드에 해당합니다 — 이 빌드의 경우, 구매 시 제공된 라이선스 파일을 런타임이 찾을 수 있는 위치에 배치합니다.

이 ionCube 라이선스 파일 메커니즘은 ionCube 인코딩 빌드에 한정됩니다. 여기서 NextPDF Enterprise 정식 제공은 ionCube 로 인코딩되었다고 가정하지 않습니다. 그 패키징과 라이선스 처리는 라이선스 약관에 의해 규정됩니다 — 라이선싱 및 활성화를 참고하세요.

정확한 경로는 환경에 따라 다르므로, 다음과 같이 일반적인 지침을 유지합니다.

NextPDF 제공 지침이 명시하는 위치에 라이선스 파일을 배치하세요 — 흔히는 인코딩된 패키지와 같은 위치이거나 애플리케이션이 읽을 수 있는 디렉터리입니다. PHP 프로세스 사용자가 읽기 권한을 갖도록 하세요.
지침에서 그렇게 하라고 명시하지 않는 한 파일 이름을 변경하지 마세요. loader 는 특정 이름을 찾습니다.
컨테이너 및 읽기 전용 배포에서는 라이선스 파일을 이미지에 마운트하거나 복사하거나, 런타임이 볼 수 있는 쓰기 가능하고 읽기 가능한 경로에 배치하세요 (Docker 및 컨테이너 참고).

라이선스 파일은 런타임 수준에서 활성화를 규정하며, 에디션과 기능을 선택하는 애플리케이션 수준의 라이선스와는 별개입니다. 약관, 기간, 구독이 부여하는 권한에 대해서는 라이선싱 및 활성화와 라이선스 계약을 참고하세요 — 이 페이지는 라이선스 약관을 정의하지 않습니다.

Troubleshooting

”Loader not installed” / “Failed loading … ioncube_loader”

코드를 실행한 런타임에서 Loader 가 활성화되지 않았거나, 경로가 잘못된 것입니다. zend_extension 줄이 절대 경로로 실제 존재하는 파일을 가리키는지, 런타임을 재시작했는지, 그리고 php -v / phpinfo() 로 동일한 런타임(CLI 대 FPM)을 검증했는지 다시 확인하세요. Failed loading 메시지는 대개 파일은 존재하지만 PHP 빌드와 일치하지 않는다는 의미입니다(다음 항목 참고).

PHP version, NTS/ZTS, or architecture mismatch

다른 PHP 버전, 스레드 안전 모드, 또는 아키텍처용으로 빌드된 Loader 는 로드되지 않습니다. php -i 에서 PHP Version, Thread Safety, Architecture 를 확인한 뒤, 일치하는 NTS/ZTS 와 비트 수에 맞는 PHP 8.4 용 Loader 파일을 설치하세요. 8.4 와 8.4_ts(또는 _ts.dll) 접미사는 스레드 안전 선택자이며, 잘못된 것을 사용하는 것이 흔한 실수입니다.

Loader load order

ionCube Loader 는 zend_extension 이어야 하며 다른 확장보다 먼저 초기화되어야 합니다. Loader 가 다른 확장 이후에 로드된다는 경고가 보이면 zend_extension 줄을 더 앞으로 옮기거나, conf.d 구성에서는 include 파일에 가장 먼저 정렬되는 이름(예: 00-ioncube.ini)을 부여하세요.

CLI, FPM, and the web server use different php.ini files

PHP 는 흔히 CLI 와 PHP-FPM 또는 mod_php 에 대해 서로 다른 php.ini 를 로드합니다. CLI 만 구성하면 웹 런타임에는 Loader 가 없게 되며(또는 그 반대), 이 경우 문제가 발생합니다. php --ini 를 실행하여 CLI 가 사용하는 파일을 확인하고, 웹 phpinfo() 출력의 Loaded Configuration File 줄을 확인하세요. NextPDF 를 실행하는 모든 php.ini 에 zend_extension 줄을 추가하고, 각 런타임을 재시작하세요.

License file not found or expired

유료 ionCube 인코딩 Pro 빌드의 경우, 라이선스 파일이 없거나 읽을 수 없거나 만료되면 인코딩된 코드가 실행되지 않습니다. 파일이 예상 위치에 있는지, PHP 프로세스 사용자가 읽을 수 있는지, 그리고 만료되지 않았는지 확인하세요. 갱신 및 기간 관련 문의는 라이선싱 및 활성화와 라이선스 계약을 참고하세요.

OPcache interactions

OPcache 는 컴파일된 스크립트를 캐시하지만, ionCube 로 인코딩된 파일은 런타임에 Loader 가 디코딩합니다. Loader 또는 그 구성을 변경했는데도 런타임이 여전히 Loader 가 없는 것처럼 동작한다면, 핫 리로드에 의존하지 말고 PHP 런타임을 재시작하세요(이는 OPcache 를 비웁니다). ionCube zend_extension 을 계속 등록해 두어 OPcache 보다 먼저 로드되도록 하세요. 둘은 공존하며, php -v 는 둘 다 표시해야 합니다.

Docker and containers

컨테이너화된 배포에서는 Loader 를 이미지 안에 설치하고, 호스트가 아니라 컨테이너의 PHP 빌드와 일치하는지 확인하세요. 베이스 이미지가 PHP 버전, OS, 아키텍처, 스레드 안전 모드를 고정하므로, 그 값에 맞는 Loader 번들을 다운로드하세요.

전형적인 이미지 빌드는 다음과 같습니다.

PHP 8.4 베이스 이미지에서 시작하세요(NTS 인지 ZTS 인지 확인하세요 — 공식 php:8.4-cli / 8.4-fpm / 8.4-apache 태그는 NTS 이며, zts 가 포함된 태그는 스레드 안전입니다. 이에 맞는 Loader 를 선택하세요).
일치하는 ionCube Loader 파일을 이미지의 extension_dir 에 추가하세요.
이미지의 php.ini(또는 conf.d include)에 zend_extension=... 줄을 작성하세요.
유료 ionCube 인코딩 Pro 빌드의 경우, 라이선스 파일을 이미지에 복사하거나 컨테이너가 읽을 수 있는 경로에 런타임에 마운트하여 제공하세요.

Loader 가 이미지에 내장되어 있으므로 동일한 컨테이너는 어디서나 동일하게 실행됩니다. 이후 베이스 이미지의 PHP 를 업그레이드하면, Loader 파일을 새 런타임과 일치하는 빌드로 교체하세요.