Настройка ionCube Loader для премиум-редакций NextPDF

Краткий обзор

Некоторые премиум-дистрибутивы NextPDF поставляются как PHP с кодированием ionCube, поэтому перед запуском кода в среде выполнения PHP должен быть установлен соответствующий ionCube Loader. Это касается:

Ознакомительных (trial) сборок NextPDF Pro и Enterprise, а также
Официальной (платной) сборки NextPDF Pro.

Для официальной поставки NextPDF Enterprise механизм упаковки зависит от вашего соглашения. Следуйте инструкциям по поставке из ваших лицензионных условий, а не предполагайте конкретную среду выполнения; см. Лицензирование и активация.

Эта страница — практическое руководство по настройке: что такое ionCube, как установить и проверить Loader, куда помещается лицензионный файл для платной сборки Pro с кодированием ionCube, как запускать её в контейнерах и как устранять типичные сбои. Поддерживаемая версия PHP — 8.4, и устанавливаемый вами Loader должен точно соответствовать этой среде выполнения.

Что такое ionCube и почему NextPDF его использует

ionCube — это коммерческий кодировщик PHP в паре с бесплатным компонентом среды выполнения под названием ionCube Loader. Loader — это расширение PHP (Zend). При запуске PHP Loader позволяет декодировать и выполнять кодированные файлы; без него кодированный файл не может работать, и вместо этого PHP сообщает об ошибке загрузчика.

NextPDF использует кодирование ionCube, чтобы защитить проприетарный премиум-исходный код, продолжая при этом поставлять устанавливаемый PHP, который вы развёртываете и запускаете как любой другой пакет Composer. Кодирование не меняет способ вызова библиотеки — ваше приложение обращается к тем же публичным контрактам — оно лишь добавляет требование, чтобы Loader присутствовал в среде выполнения.

За загрузками Loader и авторитетными инструкциями для конкретной версии обращайтесь к документации поставщика на ioncube.com (документация ionCube Loader и руководство по установке). Эта страница описывает настройку, специфичную для NextPDF; источником истины по самому Loader является поставщик.

Требования

Установите ionCube Loader, который соответствует вашей среде выполнения PHP по всем параметрам. Несоответствие по любому из них — самая частая причина сбоя:

Параметр	Должно соответствовать
Версия PHP	8.4 (премиум NextPDF требует `>=8.4 <9.0`).
Операционная система	ОС, на которую рассчитан комплект Loader (Linux, Windows, macOS).
Архитектура	Архитектура процессора хоста, обычно 64-разрядная (`x86-64` или `aarch64`).
Потокобезопасность	Без потокобезопасности (NTS) или с потокобезопасностью (ZTS), в соответствии с вашей сборкой PHP.

Помимо Loader вам также понадобится:

Премиум-пакет NextPDF, установленный через Composer — nextpdf/pro, nextpdf/enterprise или метапакет nextpdf/premium.
Для платных сборок — ваш лицензионный файл. Для платной сборки Pro с кодированием ionCube см. Размещение лицензии ниже.

Чтобы узнать значения вашей текущей сборки, выполните php -i (или вызовите phpinfo()) и проверьте строки PHP Version, Architecture и Thread Safety. В большинстве развёртываний CLI и PHP-FPM потокобезопасность отключена (NTS); классический Apache mod_php на некоторых платформах работает в режиме ZTS. Загрузите комплект Loader для этих точных значений.

Установка Loader

Шаги ниже — это общий порядок действий. За точными именами файлов и структурой каталогов текущего комплекта обращайтесь к документации ionCube Loader на ioncube.com.

Загрузите комплект Loader, соответствующий вашему окружению (PHP 8.4, ваша ОС, архитектура и NTS/ZTS). Комплект содержит по одному файлу загрузчика для каждой версии PHP и варианта потокобезопасности.
Поместите файл загрузчика в каталог расширений PHP. Используйте extension_dir, который сообщает php -i. В 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 должен загружаться как zend_extension, а не как обычное extension, и его следует загружать раньше других расширений. Добавьте одну строку, используя абсолютный путь к файлу загрузчика:
```
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, поместите эту строку в файл, который читается рано (например, 00-ioncube.ini), чтобы Loader инициализировался раньше других расширений.
Перезапустите среду выполнения PHP. Перезапустите PHP-FPM, ваш веб-сервер (Apache/Nginx) или просто заново запустите CLI — то, что выполняет ваше приложение. Длительно работающий процесс сохраняет старую конфигурацию до перезапуска.

Проверка

Прежде чем пытаться загрузить 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 настроен правильно.

Размещение лицензии (платная сборка Pro с кодированием ionCube)

ionCube использует простую модель лицензирования: кодированный код во время выполнения проверяет наличие лицензионного файла и отказывается работать, если файл отсутствует, нечитаем или просрочен. Это касается платной сборки Pro с кодированием ionCube — для неё вы помещаете лицензионный файл, предоставленный при покупке, туда, где среда выполнения может его найти.

Этот механизм лицензионного файла ionCube специфичен для сборки с кодированием ionCube. Здесь не предполагается, что официальная поставка NextPDF Enterprise имеет кодирование ionCube; её упаковка и обработка лицензии регулируются вашими лицензионными условиями — см. Лицензирование и активация.

Точные пути зависят от окружения, поэтому держите это описание общим:

Поместите лицензионный файл туда, где указано в инструкциях по поставке вашего дистрибутива NextPDF — обычно рядом с кодированным пакетом или в каталоге, доступном приложению для чтения. Убедитесь, что у пользователя процесса PHP есть права на чтение.
Не переименовывайте файл, если этого не требуют ваши инструкции; загрузчик ищет определённое имя.
В контейнерах и в развёртываниях только для чтения смонтируйте или скопируйте лицензионный файл в образ либо в доступный для записи и чтения путь, видимый среде выполнения (см. Docker и контейнеры).

Лицензионный файл управляет активацией на уровне среды выполнения; он отделён от лицензии уровня приложения, которая выбирает вашу редакцию и возможности. Условия, сроки и состав того, что даёт ваша подписка, см. в разделе Лицензирование и активация и в вашем лицензионном соглашении — эта страница не определяет лицензионные условия.

Устранение неполадок

«Loader not installed» / «Failed loading … ioncube_loader»

Loader не активен в среде выполнения, которая запустила код, либо путь неверен. Перепроверьте, что строка zend_extension указывает на существующий файл по абсолютному пути, что вы перезапустили среду выполнения и что проверили ту же среду выполнения (CLI или FPM) через php -v / phpinfo(). Сообщение Failed loading обычно означает, что файл существует, но не соответствует сборке PHP (см. следующий пункт).

Несоответствие версии PHP, NTS/ZTS или архитектуры

Loader, собранный для другой версии PHP, режима потокобезопасности или архитектуры, не загрузится. Подтвердите PHP Version, Thread Safety и Architecture из php -i, затем установите файл Loader для PHP 8.4 с соответствующими NTS/ZTS и разрядностью. Суффикс 8.4 или 8.4_ts (либо _ts.dll) — это селектор потокобезопасности; выбор неправильного варианта — частая ошибка.

Порядок загрузки Loader

ionCube Loader должен быть zend_extension и инициализироваться раньше других расширений. Если вы видите предупреждения о том, что Loader загружается после других расширений, переместите его строку zend_extension выше — либо при структуре conf.d дайте его включаемому файлу имя, которое сортируется первым (например, 00-ioncube.ini).

CLI, FPM и веб-сервер используют разные файлы php.ini

PHP часто загружает разный php.ini для CLI и для PHP-FPM или mod_php. Настройка только для CLI оставляет веб-среду выполнения без Loader (или наоборот). Выполните php --ini, чтобы увидеть, какой файл использует CLI, и проверьте строку Loaded Configuration File в выводе веб-вызова phpinfo(). Добавьте строку zend_extension в каждый php.ini, который запускает NextPDF, и перезапустите каждую среду выполнения.

Лицензионный файл не найден или просрочен

Для платной сборки Pro с кодированием ionCube отсутствующий, нечитаемый или просроченный лицензионный файл останавливает выполнение кодированного кода. Убедитесь, что файл находится в ожидаемом месте, что пользователь процесса PHP может его прочитать и что срок его действия не истёк. По вопросам продления и сроков см. Лицензирование и активация и ваше лицензионное соглашение.

Взаимодействие с OPcache

OPcache кэширует скомпилированные скрипты, но файлы с кодированием ionCube декодируются Loader во время выполнения. Если вы изменили Loader или его конфигурацию, а среда выполнения по-прежнему ведёт себя так, будто его нет, перезапустите среду выполнения PHP (что очищает OPcache), а не полагайтесь на горячую перезагрузку. Сохраняйте регистрацию zend_extension ionCube, чтобы он загружался раньше OPcache; они сосуществуют, и php -v должен перечислять оба.

Docker и контейнеры

В контейнеризированном развёртывании установите Loader в образ и убедитесь, что он соответствует сборке PHP контейнера, а не вашего хоста. Базовый образ фиксирует версию PHP, ОС, архитектуру и режим потокобезопасности, поэтому загрузите комплект Loader для этих значений.

Типичная сборка образа:

Начните с базового образа PHP 8.4 (обратите внимание, NTS это или ZTS — официальные теги php:8.4-cli / 8.4-fpm / 8.4-apache относятся к NTS, а теги, содержащие zts, — потокобезопасны; выберите Loader под соответствие).
Добавьте соответствующий файл ionCube Loader в extension_dir образа.
Запишите строку zend_extension=... в php.ini образа (или во включаемый файл conf.d).
Для платной сборки Pro с кодированием ionCube предоставьте лицензионный файл, скопировав его в образ или смонтировав во время выполнения в путь, доступный контейнеру для чтения.

Поскольку Loader встроен в образ, один и тот же контейнер работает одинаково везде. Если позже вы обновите PHP базового образа, замените файл Loader на сборку, соответствующую новой среде выполнения.