Thiết lập ionCube Loader cho các phiên bản NextPDF premium

Tổng quan nhanh

Một số bản phân phối NextPDF premium được phát hành dưới dạng PHP mã hóa bằng ionCube, nên ionCube Loader tương ứng phải được cài đặt trong runtime PHP của bạn trước khi mã có thể chạy. Điều này áp dụng cho:

Các bản dựng dùng thử của NextPDF Pro và Enterprise, và
Bản dựng chính thức (trả phí) của NextPDF Pro.

Đối với bản giao hàng chính thức của NextPDF Enterprise, cơ chế đóng gói phụ thuộc vào thỏa thuận của bạn. Hãy làm theo hướng dẫn giao hàng trong các điều khoản giấy phép thay vì giả định một runtime cụ thể; xem Cấp phép và kích hoạt.

Trang này là một hướng dẫn thiết lập thực hành: ionCube là gì, cách cài đặt và xác minh Loader, nơi đặt giấy phép cho bản dựng Pro trả phí được mã hóa bằng ionCube, cách chạy nó trong container, và cách khắc phục các lỗi thường gặp. Phiên bản PHP được hỗ trợ là 8.4, và Loader bạn cài đặt phải khớp chính xác với runtime đó.

ionCube là gì và vì sao NextPDF dùng nó

ionCube là một trình mã hóa PHP thương mại đi kèm một thành phần runtime miễn phí gọi là ionCube Loader. Loader là một extension PHP (Zend). Khi PHP khởi động, Loader cho phép các tệp đã mã hóa được giải mã và thực thi; nếu không có nó, một tệp đã mã hóa không thể chạy và PHP báo lỗi loader thay vào đó.

NextPDF dùng mã hóa ionCube để bảo vệ mã nguồn premium độc quyền trong khi vẫn phát hành PHP có thể cài đặt mà bạn triển khai và chạy như mọi gói Composer khác. Việc mã hóa không thay đổi cách bạn gọi thư viện — ứng dụng của bạn vẫn nhắm tới cùng các public contract — nó chỉ thêm yêu cầu rằng Loader phải hiện diện trong runtime.

Để tải Loader và xem hướng dẫn chính thức theo từng phiên bản, hãy dùng tài liệu của nhà cung cấp tại ioncube.com (tài liệu và hướng dẫn cài đặt ionCube Loader). Trang này bao quát phần thiết lập riêng cho NextPDF; nhà cung cấp là nguồn chính thống cho bản thân Loader.

Yêu cầu

Hãy cài đặt ionCube Loader khớp với runtime PHP của bạn trên mọi trục. Lệch ở bất kỳ trục nào trong số này là nguyên nhân gây lỗi phổ biến nhất:

Trục	Phải khớp
Phiên bản PHP	8.4 (NextPDF premium yêu cầu `>=8.4 <9.0`).
Hệ điều hành	Hệ điều hành mà gói Loader nhắm tới (Linux, Windows, macOS).
Kiến trúc	Kiến trúc CPU của máy chủ, thường là 64-bit (`x86-64` hoặc `aarch64`).
Thread safety	Non-thread-safe (NTS) hoặc thread-safe (ZTS), khớp với bản dựng PHP của bạn.

Ngoài Loader, bạn cũng cần:

Gói NextPDF premium được cài đặt qua Composer — nextpdf/pro, nextpdf/enterprise, hoặc metapackage nextpdf/premium.
Đối với các bản dựng trả phí, tệp giấy phép của bạn. Với bản dựng Pro trả phí được mã hóa bằng ionCube, xem Đặt giấy phép bên dưới.

Để đọc các giá trị của bản dựng hiện tại, hãy chạy php -i (hoặc gọi phpinfo()) và kiểm tra các dòng PHP Version, Architecture, và Thread Safety. Trên hầu hết các triển khai CLI và PHP-FPM, thread safety bị vô hiệu hóa (NTS); Apache mod_php cổ điển trên một số nền tảng là ZTS. Hãy tải gói Loader cho đúng các giá trị đó.

Cài đặt Loader

Các bước dưới đây là quy trình tổng quát. Hãy tham chiếu tài liệu ionCube Loader trên ioncube.com để biết chính xác tên tệp và bố cục thư mục của gói hiện tại.

Tải gói Loader khớp với môi trường của bạn (PHP 8.4, hệ điều hành, kiến trúc, và NTS/ZTS). Gói chứa một tệp loader cho mỗi phiên bản PHP và biến thể thread-safety.
Đặt tệp loader vào thư mục extension của PHP. Dùng extension_dir được báo cáo bởi php -i. Trên Linux/macOS, tệp là ioncube_loader_<os>_8.4.so (dùng ..._8.4_ts.so cho bản dựng ZTS); trên Windows, đó là ioncube_loader_win_8.4.dll (hoặc biến thể ZTS ..._ts.dll).
Đăng ký nó trong php.ini dưới dạng một zend_extension. ionCube Loader phải nạp dưới dạng một zend_extension, không phải một extension thông thường, và nó nên nạp trước các extension khác. Hãy thêm một dòng duy nhất, dùng đường dẫn tuyệt đối đến tệp loader:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
Trên Windows, dùng đường dẫn đầy đủ đến tệp .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Nếu nền tảng của bạn dùng các thư mục include kiểu conf.d, hãy đặt dòng này vào một tệp được đọc sớm (ví dụ một tệp 00-ioncube.ini) để Loader khởi tạo trước các extension khác.
Khởi động lại runtime PHP. Khởi động lại PHP-FPM, máy chủ web của bạn (Apache/Nginx), hoặc đơn giản là chạy lại CLI — tùy theo nơi ứng dụng của bạn chạy. Một tiến trình chạy lâu vẫn giữ cấu hình cũ cho đến khi được khởi động lại.

Xác minh

Hãy xác nhận Loader đang hoạt động trước khi bạn thử nạp NextPDF.

Trước tiên, hãy kiểm tra dòng thông báo phiên bản PHP. Khi Loader đã được cài đặt, php -v nối thêm một dòng nêu tên nó:

php -v

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

Cụm từ “with the ionCube PHP Loader” là dấu hiệu cho thấy Loader đang hoạt động cho runtime đó. Đối với một triển khai web (FPM / mod_php), dòng thông báo của CLI là chưa đủ — runtime đó có thể dùng một php.ini khác. Hãy xác nhận runtime web bằng một script nhỏ do máy chủ web phục vụ:

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

Cuối cùng, hãy xác nhận rằng một lớp NextPDF premium thực sự nạp được qua autoloader của Composer. Điều này chứng minh mã đã mã hóa chạy được từ đầu đến cuối:

<?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));

Nếu php -v nêu tên Loader, phpinfo() của web hiển thị mục ionCube, và lớp premium nạp được, thì Loader đã được thiết lập đúng cách.

Đặt giấy phép (bản dựng Pro trả phí được mã hóa bằng ionCube)

ionCube dùng một mô hình cấp phép đơn giản: mã đã mã hóa kiểm tra một tệp giấy phép tại runtime và từ chối chạy khi tệp bị thiếu, không đọc được, hoặc đã hết hạn. Điều này áp dụng cho bản dựng Pro trả phí được mã hóa bằng ionCube — với nó, bạn đặt tệp giấy phép mà gói mua hàng của bạn cung cấp vào nơi runtime có thể tìm thấy.

Cơ chế tệp-giấy-phép của ionCube này là riêng cho bản dựng được mã hóa bằng ionCube. Bản giao hàng chính thức của NextPDF Enterprise không được giả định là được mã hóa bằng ionCube ở đây; việc đóng gói và xử lý giấy phép của nó được quy định bởi các điều khoản giấy phép của bạn — xem Cấp phép và kích hoạt.

Đường dẫn chính xác phụ thuộc vào môi trường, nên hãy giữ phần này ở mức tổng quát:

Đặt tệp giấy phép vào vị trí mà hướng dẫn giao hàng NextPDF của bạn chỉ định — thường là cạnh gói đã mã hóa hoặc trong một thư mục mà ứng dụng có thể đọc. Hãy chắc chắn rằng user của tiến trình PHP có quyền đọc.
Đừng đổi tên tệp trừ khi hướng dẫn của bạn yêu cầu; loader tìm một tên cụ thể.
Trong container và trên các triển khai chỉ-đọc, hãy mount hoặc sao chép tệp giấy phép vào image hoặc một đường dẫn có thể ghi và đọc mà runtime nhìn thấy (xem Docker và container).

Tệp giấy phép quy định việc kích hoạt ở cấp độ runtime; nó tách biệt với giấy phép ở cấp độ ứng dụng vốn chọn phiên bản và các tính năng của bạn. Để biết các điều khoản, thời hạn và những gì gói thuê bao của bạn cho phép, hãy xem Cấp phép và kích hoạt và thỏa thuận giấy phép của bạn — trang này không định nghĩa các điều khoản giấy phép.

Xử lý sự cố

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

Loader không hoạt động trong runtime đã chạy mã, hoặc đường dẫn bị sai. Hãy kiểm tra lại rằng dòng zend_extension trỏ đến một tệp đang tồn tại bằng đường dẫn tuyệt đối, rằng bạn đã khởi động lại runtime, và rằng bạn đã xác minh cùng một runtime (CLI so với FPM) bằng php -v / phpinfo(). Một thông báo Failed loading thường có nghĩa là tệp tồn tại nhưng không khớp với bản dựng PHP (xem mục tiếp theo).

Lệch phiên bản PHP, NTS/ZTS, hoặc kiến trúc

Một Loader được dựng cho một phiên bản PHP, chế độ thread-safety, hoặc kiến trúc khác sẽ không nạp được. Hãy xác nhận PHP Version, Thread Safety, và Architecture từ php -i, rồi cài đặt tệp Loader cho PHP 8.4 với NTS/ZTS và độ rộng bit khớp. Hậu tố 8.4 so với 8.4_ts (hoặc _ts.dll) là bộ chọn thread-safety — dùng sai là một lỗi thường gặp.

Thứ tự nạp Loader

ionCube Loader phải là một zend_extension và nên khởi tạo trước các extension khác. Nếu bạn thấy cảnh báo về việc Loader nạp sau các extension khác, hãy chuyển dòng zend_extension của nó lên sớm hơn — hoặc, với bố cục conf.d, đặt cho tệp include của nó một tên sắp xếp lên đầu (ví dụ 00-ioncube.ini).

CLI, FPM, và máy chủ web dùng các tệp php.ini khác nhau

PHP thường nạp một php.ini khác cho CLI so với cho PHP-FPM hoặc mod_php. Cấu hình chỉ cho CLI sẽ khiến runtime web không có Loader (hoặc ngược lại). Hãy chạy php --ini để xem tệp nào mà CLI dùng, và kiểm tra dòng Loaded Configuration File trong đầu ra phpinfo() của web. Hãy thêm dòng zend_extension vào mọi php.ini chạy NextPDF, và khởi động lại từng runtime.

Tệp giấy phép không tìm thấy hoặc đã hết hạn

Đối với bản dựng Pro trả phí được mã hóa bằng ionCube, một tệp giấy phép bị thiếu, không đọc được, hoặc đã hết hạn sẽ làm dừng việc chạy mã đã mã hóa. Hãy xác minh rằng tệp nằm ở vị trí dự kiến, rằng user của tiến trình PHP có thể đọc nó, và rằng nó chưa hết hạn. Để biết về gia hạn và các câu hỏi về thời hạn, hãy xem Cấp phép và kích hoạt và thỏa thuận giấy phép của bạn.

Tương tác với OPcache

OPcache lưu vào bộ nhớ đệm các script đã biên dịch, nhưng các tệp được mã hóa bằng ionCube lại được Loader giải mã tại runtime. Nếu bạn đã thay đổi Loader hoặc cấu hình của nó mà runtime vẫn hành xử như thể nó vắng mặt, hãy khởi động lại runtime PHP (việc này xóa OPcache) thay vì dựa vào một lần nạp lại nóng. Hãy giữ zend_extension của ionCube được đăng ký để nó nạp trước OPcache; cả hai cùng tồn tại, và php -v sẽ liệt kê cả hai.

Docker và container

Trong một triển khai đóng gói bằng container, hãy cài đặt Loader trong image, và đảm bảo nó khớp với bản dựng PHP của container — không phải của máy chủ của bạn. Base image cố định phiên bản PHP, hệ điều hành, kiến trúc, và chế độ thread-safety, nên hãy tải gói Loader cho các giá trị đó.

Một quy trình dựng image điển hình:

Bắt đầu từ một base image PHP 8.4 (lưu ý nó là NTS hay ZTS — các tag chính thức php:8.4-cli / 8.4-fpm / 8.4-apache là NTS, còn các tag chứa zts là thread-safe; hãy chọn Loader cho khớp).
Thêm tệp ionCube Loader khớp vào extension_dir của image.
Ghi dòng zend_extension=... vào php.ini của image (hoặc một include conf.d).
Đối với bản dựng Pro trả phí được mã hóa bằng ionCube, hãy cung cấp tệp giấy phép bằng cách sao chép nó vào image hoặc mount nó tại runtime vào một đường dẫn mà container có thể đọc.

Vì Loader được dựng sẵn vào image, cùng một container chạy y hệt ở mọi nơi. Nếu sau này bạn nâng cấp PHP của base image, hãy thay tệp Loader bằng bản dựng khớp với runtime mới.