Konfiguracja ionCube Loader dla edycji premium NextPDF

W skrócie

Niektóre dystrybucje premium NextPDF są dostarczane jako kod PHP zakodowany przez ionCube, dlatego odpowiadający mu ionCube Loader musi być zainstalowany w środowisku uruchomieniowym PHP, zanim kod zacznie działać. Dotyczy to:

Kompilacji ewaluacyjnych NextPDF Pro i Enterprise oraz
Oficjalnej (płatnej) kompilacji NextPDF Pro.

W przypadku oficjalnego dostarczenia NextPDF Enterprise mechanizm pakowania zależy od Twojej umowy. Postępuj zgodnie z instrukcjami dostarczania zawartymi w warunkach licencji, zamiast zakładać konkretne środowisko uruchomieniowe; zobacz Licencjonowanie i aktywacja.

Ta strona to praktyczny przewodnik konfiguracji: czym jest ionCube, jak zainstalować i zweryfikować Loader, gdzie umieścić plik licencji w przypadku płatnej, zakodowanej przez ionCube kompilacji Pro, jak uruchomić go w kontenerach oraz jak naprawić typowe błędy. Obsługiwana wersja PHP to 8.4, a zainstalowany Loader musi dokładnie odpowiadać temu środowisku uruchomieniowemu.

Czym jest ionCube i dlaczego NextPDF go używa

ionCube to komercyjny enkoder PHP połączony z bezpłatnym komponentem uruchomieniowym nazywanym ionCube Loader. Loader to rozszerzenie PHP (Zend). Gdy PHP się uruchamia, Loader umożliwia zdekodowanie i wykonanie zakodowanych plików; bez niego zakodowany plik nie może działać, a PHP zgłasza zamiast tego błąd Loadera.

NextPDF używa kodowania ionCube, aby chronić zastrzeżony kod źródłowy premium, jednocześnie dostarczając instalowalny kod PHP, który wdrażasz i uruchamiasz tak jak każdy inny pakiet Composer. Kodowanie nie zmienia sposobu wywoływania biblioteki — Twoja aplikacja korzysta z tych samych publicznych kontraktów — dodaje jedynie wymóg obecności Loadera w środowisku uruchomieniowym.

Aby pobrać Loader oraz uzyskać autorytatywne, specyficzne dla wersji instrukcje, skorzystaj z dokumentacji dostawcy na stronie ioncube.com (dokumentacja i przewodnik instalacji ionCube Loader). Ta strona obejmuje konfigurację specyficzną dla NextPDF; źródłem prawdy dla samego Loadera jest dostawca.

Wymagania

Zainstaluj ionCube Loader odpowiadający Twojemu środowisku uruchomieniowemu PHP pod każdym względem. Niezgodność w którymkolwiek z tych aspektów jest najczęstszą przyczyną awarii:

Aspekt	Musi się zgadzać
Wersja PHP	8.4 (NextPDF premium wymaga `>=8.4 <9.0`).
System operacyjny	System operacyjny, dla którego przeznaczony jest pakiet Loadera (Linux, Windows, macOS).
Architektura	Architektura procesora hosta, zwykle 64-bitowa (`x86-64` lub `aarch64`).
Bezpieczeństwo wątków	Wersja bez obsługi wątków (NTS) lub z obsługą wątków (ZTS), odpowiadająca Twojej kompilacji PHP.

Poza Loaderem potrzebujesz również:

Pakietu premium NextPDF zainstalowanego przez Composer — nextpdf/pro, nextpdf/enterprise lub metapakietu nextpdf/premium.
W przypadku płatnych kompilacji — Twojego pliku licencji. W przypadku płatnej, zakodowanej przez ionCube kompilacji Pro zobacz Umieszczenie licencji poniżej.

Aby odczytać bieżące wartości swojej kompilacji, uruchom php -i (lub wywołaj phpinfo()) i sprawdź wiersze PHP Version, Architecture oraz Thread Safety. W większości wdrożeń CLI i PHP-FPM bezpieczeństwo wątków jest wyłączone (NTS); klasyczny Apache mod_php na niektórych platformach jest w trybie ZTS. Pobierz pakiet Loadera odpowiadający tym dokładnym wartościom.

Instalacja Loadera

Poniższe kroki to ogólny przebieg. W kwestii dokładnych nazw plików i układu katalogów bieżącego pakietu odwołaj się do dokumentacji ionCube Loader na stronie ioncube.com.

Pobierz pakiet Loadera odpowiadający Twojemu środowisku (PHP 8.4, Twój system operacyjny, architektura oraz NTS/ZTS). Pakiet zawiera jeden plik loadera na każdą wersję PHP i wariant bezpieczeństwa wątków.
Umieść plik loadera w katalogu rozszerzeń PHP. Użyj katalogu extension_dir zgłaszanego przez php -i. W systemach Linux/macOS plikiem jest ioncube_loader_<os>_8.4.so (dla kompilacji ZTS użyj ..._8.4_ts.so); w systemie Windows jest to ioncube_loader_win_8.4.dll (lub wariant ZTS ..._ts.dll).
Zarejestruj go w php.ini jako zend_extension. ionCube Loader musi się wczytywać jako zend_extension, a nie zwykłe extension, i powinien wczytywać się przed innymi rozszerzeniami. Dodaj pojedynczy wiersz, używając bezwzględnej ścieżki do pliku loadera:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
W systemie Windows użyj pełnej ścieżki do pliku .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Jeśli Twoja platforma korzysta z katalogów dołączanych w stylu conf.d, umieść ten wiersz w pliku odczytywanym wcześnie (na przykład 00-ioncube.ini), aby Loader inicjalizował się przed innymi rozszerzeniami.
Uruchom ponownie środowisko uruchomieniowe PHP. Uruchom ponownie PHP-FPM, serwer WWW (Apache/Nginx) lub po prostu ponownie uruchom CLI — w zależności od tego, co uruchamia Twoją aplikację. Długo działający proces zachowuje starą konfigurację, dopóki nie zostanie ponownie uruchomiony.

Weryfikacja

Potwierdź, że Loader jest aktywny, zanim spróbujesz wczytać NextPDF.

Najpierw sprawdź baner wersji PHP. Gdy Loader jest zainstalowany, php -v dołącza wiersz, który go nazywa:

php -v

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

Fraza „with the ionCube PHP Loader” to sygnał, że Loader jest aktywny dla tego środowiska uruchomieniowego. W przypadku wdrożenia webowego (FPM / mod_php) baner CLI nie wystarcza — to środowisko uruchomieniowe może używać innego pliku php.ini. Potwierdź środowisko webowe za pomocą małego skryptu obsługiwanego przez serwer WWW:

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

Na koniec potwierdź, że klasa premium NextPDF faktycznie wczytuje się przez autoloader Composera. Dowodzi to, że zakodowany kod działa od początku do końca:

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

Jeśli php -v nazywa Loader, webowe phpinfo() pokazuje sekcję ionCube, a klasa premium się rozwiązuje, Loader jest poprawnie skonfigurowany.

Umieszczenie licencji (płatna, zakodowana przez ionCube kompilacja Pro)

ionCube stosuje prosty model licencjonowania: zakodowany kod sprawdza obecność pliku licencji w czasie wykonywania i odmawia działania, gdy plik jest brakujący, nieczytelny lub wygasły. Dotyczy to płatnej, zakodowanej przez ionCube kompilacji Pro — w jej przypadku umieszczasz plik licencji dostarczony wraz z zakupem w miejscu, w którym środowisko uruchomieniowe może go znaleźć.

Ten mechanizm pliku licencji ionCube jest specyficzny dla kompilacji zakodowanej przez ionCube. Oficjalne dostarczenie NextPDF Enterprise nie jest tutaj zakładane jako zakodowane przez ionCube; jego pakowanie i obsługa licencji są regulowane warunkami Twojej licencji — zobacz Licencjonowanie i aktywacja.

Dokładne ścieżki zależą od środowiska, dlatego pozostań przy ogólnych zasadach:

Umieść plik licencji w lokalizacji wskazanej w instrukcjach dostarczania NextPDF — zwykle obok zakodowanego pakietu lub w katalogu, który aplikacja może odczytać. Upewnij się, że użytkownik procesu PHP ma uprawnienia do odczytu.
Nie zmieniaj nazwy pliku, chyba że instrukcje na to wskazują; loader szuka konkretnej nazwy.
W kontenerach i we wdrożeniach tylko do odczytu zamontuj lub skopiuj plik licencji do obrazu albo do zapisywalnej, czytelnej ścieżki widocznej dla środowiska uruchomieniowego (zobacz Docker i kontenery).

Plik licencji reguluje aktywację na poziomie środowiska uruchomieniowego; jest odrębny od licencji na poziomie aplikacji, która wybiera Twoją edycję i funkcje. Aby poznać warunki, okresy obowiązywania oraz to, do czego uprawnia Twoja subskrypcja, zobacz Licencjonowanie i aktywacja oraz swoją umowę licencyjną — ta strona nie definiuje warunków licencji.

Rozwiązywanie problemów

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

Loader nie jest aktywny w środowisku uruchomieniowym, które uruchomiło kod, albo ścieżka jest nieprawidłowa. Sprawdź ponownie, czy wiersz zend_extension wskazuje istniejący plik za pomocą bezwzględnej ścieżki, czy ponownie uruchomiono środowisko uruchomieniowe oraz czy zweryfikowano to samo środowisko (CLI vs FPM) za pomocą php -v / phpinfo(). Komunikat Failed loading zwykle oznacza, że plik istnieje, ale nie odpowiada kompilacji PHP (zobacz następny punkt).

Niezgodność wersji PHP, NTS/ZTS lub architektury

Loader zbudowany dla innej wersji PHP, trybu bezpieczeństwa wątków lub architektury nie zostanie wczytany. Potwierdź wartości PHP Version, Thread Safety oraz Architecture z php -i, a następnie zainstaluj plik Loadera dla PHP 8.4 z odpowiednim trybem NTS/ZTS i rozmiarem słowa. Sufiks 8.4 vs 8.4_ts (lub _ts.dll) to selektor bezpieczeństwa wątków — użycie niewłaściwego jest częstym błędem.

Kolejność wczytywania Loadera

ionCube Loader musi być zend_extension i powinien inicjalizować się przed innymi rozszerzeniami. Jeśli widzisz ostrzeżenia o wczytywaniu Loadera po innych rozszerzeniach, przesuń jego wiersz zend_extension wcześniej — lub, w układzie conf.d, nadaj jego plikowi dołączanemu nazwę, która sortuje się jako pierwsza (na przykład 00-ioncube.ini).

CLI, FPM i serwer WWW używają różnych plików php.ini

PHP często wczytuje inny plik php.ini dla CLI niż dla PHP-FPM lub mod_php. Skonfigurowanie tylko CLI pozostawia webowe środowisko uruchomieniowe bez Loadera (lub odwrotnie). Uruchom php --ini, aby zobaczyć, którego pliku używa CLI, i sprawdź wiersz Loaded Configuration File w webowym wyniku phpinfo(). Dodaj wiersz zend_extension do każdego pliku php.ini, który uruchamia NextPDF, i uruchom ponownie każde środowisko uruchomieniowe.

Nie znaleziono pliku licencji lub plik wygasł

W przypadku płatnej, zakodowanej przez ionCube kompilacji Pro brakujący, nieczytelny lub wygasły plik licencji zatrzymuje działanie zakodowanego kodu. Sprawdź, czy plik znajduje się w oczekiwanej lokalizacji, czy użytkownik procesu PHP może go odczytać oraz czy nie wygasł. W kwestiach odnowienia i okresu obowiązywania zobacz Licencjonowanie i aktywacja oraz swoją umowę licencyjną.

Interakcje z OPcache

OPcache buforuje skompilowane skrypty, ale pliki zakodowane przez ionCube są dekodowane przez Loader w czasie wykonywania. Jeśli zmieniono Loader lub jego konfigurację, a środowisko uruchomieniowe nadal zachowuje się tak, jakby był nieobecny, uruchom ponownie środowisko uruchomieniowe PHP (co czyści OPcache), zamiast polegać na przeładowaniu na gorąco. Pozostaw zarejestrowany zend_extension ionCube, aby wczytywał się przed OPcache; oba współistnieją, a php -v powinno wymieniać obie pozycje.

Docker i kontenery

We wdrożeniu kontenerowym zainstaluj Loader w obrazie i upewnij się, że odpowiada kompilacji PHP kontenera — a nie Twojego hosta. Obraz bazowy ustala wersję PHP, system operacyjny, architekturę oraz tryb bezpieczeństwa wątków, więc pobierz pakiet Loadera dla tych wartości.

Typowa budowa obrazu:

Zacznij od obrazu bazowego PHP 8.4 (zwróć uwagę, czy jest to NTS czy ZTS — oficjalne tagi php:8.4-cli / 8.4-fpm / 8.4-apache są w trybie NTS, podczas gdy tagi zawierające zts obsługują wątki; wybierz Loader tak, aby pasował).
Dodaj odpowiedni plik ionCube Loader do katalogu extension_dir obrazu.
Wpisz wiersz zend_extension=... do pliku php.ini obrazu (lub do pliku dołączanego w conf.d).
W przypadku płatnej, zakodowanej przez ionCube kompilacji Pro dostarcz plik licencji, kopiując go do obrazu lub montując w czasie wykonywania w ścieżce, którą kontener może odczytać.

Ponieważ Loader jest wbudowany w obraz, ten sam kontener działa identycznie wszędzie. Jeśli później zaktualizujesz PHP w obrazie bazowym, zastąp plik Loadera kompilacją odpowiadającą nowemu środowisku uruchomieniowemu.