ตั้งค่า ionCube Loader สำหรับ NextPDF รุ่น premium

At a glance

NextPDF รุ่น premium บางรูปแบบจัดส่งมาเป็น PHP ที่ เข้ารหัสด้วย ionCube ดังนั้นต้องติดตั้ง ionCube Loader ที่ตรงกันในรันไทม์ PHP ของคุณก่อนโค้ดจึงจะทำงานได้ ซึ่งใช้กับ:

• บิลด์ ทดลองใช้ ของ NextPDF Pro และ Enterprise และ
• บิลด์ official (ชำระเงิน) ของ NextPDF Pro

สำหรับการส่งมอบ NextPDF Enterprise official กลไกการบรรจุแพ็กเกจขึ้นอยู่กับข้อตกลงของคุณ ให้ปฏิบัติตามคำแนะนำการส่งมอบในข้อกำหนดสิทธิ์การใช้งานของคุณ แทนการสันนิษฐานว่าใช้รันไทม์แบบใดแบบหนึ่ง ดู Licensing and activation

หน้านี้เป็นคู่มือการตั้งค่าเชิงปฏิบัติ ได้แก่ ionCube คืออะไร วิธีติดตั้งและตรวจสอบ Loader ตำแหน่งที่ไฟล์สิทธิ์การใช้งานต้องอยู่สำหรับบิลด์ Pro แบบชำระเงินที่เข้ารหัสด้วย ionCube วิธีรันใน container และวิธีแก้ปัญหาที่พบบ่อย เวอร์ชัน PHP ที่รองรับคือ 8.4 และ Loader ที่คุณติดตั้งต้องตรงกับรันไทม์นั้นพอดี

What ionCube is and why NextPDF uses it

ionCube คือ encoder เชิงพาณิชย์สำหรับ PHP ที่มาคู่กับส่วนประกอบรันไทม์แบบใช้ฟรีที่เรียกว่า ionCube Loader ซึ่ง Loader คือส่วนขยาย PHP (Zend) เมื่อ PHP เริ่มทำงาน Loader จะอนุญาตให้ถอดรหัสและประมวลผลไฟล์ที่เข้ารหัสได้ หากไม่มี Loader ไฟล์ที่เข้ารหัสจะทำงานไม่ได้และ PHP จะรายงานข้อผิดพลาดของ loader แทน

NextPDF ใช้การเข้ารหัสด้วย ionCube เพื่อปกป้องซอร์สโค้ด premium ที่เป็นกรรมสิทธิ์ ในขณะที่ยังคงจัดส่ง PHP ที่ติดตั้งได้ซึ่งคุณนำไปใช้งานและรันได้เหมือนแพ็กเกจ Composer อื่นๆ การเข้ารหัสไม่ได้เปลี่ยนวิธีที่คุณเรียกใช้ไลบรารี แอปพลิเคชันของคุณยังคงเรียกใช้ public contract ชุดเดิม เพียงแต่เพิ่มข้อกำหนดว่าต้องมี Loader อยู่ในรันไทม์

สำหรับการดาวน์โหลด Loader และคำแนะนำที่เป็นทางการเฉพาะตามเวอร์ชัน ให้ใช้เอกสารของผู้จำหน่ายที่ ioncube.com (เอกสารและคู่มือการติดตั้ง ionCube Loader) หน้านี้ครอบคลุมการตั้งค่าเฉพาะของ NextPDF ส่วนผู้จำหน่ายคือแหล่งข้อมูลที่ถูกต้องสำหรับตัว Loader เอง

Requirements

ติดตั้ง ionCube Loader ที่ตรงกับรันไทม์ PHP ของคุณในทุกแกน การไม่ตรงกันในข้อใดข้อหนึ่งคือสาเหตุของความล้มเหลวที่พบบ่อยที่สุด:

Axis	Must match
PHP version	8.4 (NextPDF premium ต้องการ >=8.4 <9.0)
Operating system	ระบบปฏิบัติการที่ Loader bundle รองรับ (Linux, Windows, macOS)
Architecture	สถาปัตยกรรม CPU ของโฮสต์ โดยทั่วไปเป็น 64-bit (x86-64 หรือ aarch64)
Thread safety	non-thread-safe (NTS) หรือ thread-safe (ZTS) ที่ตรงกับบิลด์ PHP ของคุณ

นอกเหนือจาก Loader แล้ว คุณยังต้องมี:

• แพ็กเกจ NextPDF premium ที่ติดตั้งผ่าน Composer ได้แก่ nextpdf/pro, nextpdf/enterprise หรือ metapackage nextpdf/premium
• สำหรับบิลด์แบบชำระเงิน คือ ไฟล์สิทธิ์การใช้งาน ของคุณ สำหรับบิลด์ Pro แบบชำระเงินที่เข้ารหัสด้วย ionCube ดู License placement ด้านล่าง

หากต้องการอ่านค่าบิลด์ปัจจุบันของคุณ ให้รัน php -i (หรือเรียก phpinfo()) แล้วตรวจสอบบรรทัด PHP Version, Architecture และ Thread Safety ในการนำไปใช้งานแบบ CLI และ PHP-FPM ส่วนใหญ่ thread safety จะ disabled (NTS) ส่วน Apache mod_php แบบดั้งเดิมบนบางแพลตฟอร์มจะเป็น ZTS ให้ดาวน์โหลด Loader bundle สำหรับค่าที่ตรงกันเหล่านั้นพอดี

Install the Loader

ขั้นตอนด้านล่างเป็นกระบวนการโดยทั่วไป ให้ยึดตามเอกสาร ionCube Loader บน ioncube.com สำหรับชื่อไฟล์และโครงสร้างไดเรกทอรีที่ถูกต้องของ bundle ปัจจุบัน

1. ดาวน์โหลด Loader bundle ที่ตรงกับสภาพแวดล้อมของคุณ (PHP 8.4, OS, สถาปัตยกรรม และ NTS/ZTS ของคุณ) bundle ประกอบด้วยไฟล์ loader หนึ่งไฟล์ต่อเวอร์ชัน PHP และต่อ thread-safety แต่ละแบบ

2. วางไฟล์ loader ไว้ในไดเรกทอรีส่วนขยาย PHP ใช้ค่า extension_dir ที่รายงานโดย php -i บน Linux/macOS ไฟล์จะเป็น ioncube_loader_<os>_8.4.so (ใช้ ..._8.4_ts.so สำหรับบิลด์ ZTS) ส่วนบน Windows จะเป็น ioncube_loader_win_8.4.dll (หรือตัวแปร ZTS ..._ts.dll)

3. ลงทะเบียนใน php.ini เป็น zend_extension ionCube Loader ต้องโหลด เป็น zend_extension ไม่ใช่ 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"

   หากแพลตฟอร์มของคุณใช้ไดเรกทอรี include แบบ conf.d ให้วางบรรทัดนี้ใน ไฟล์ที่ถูกอ่าน ก่อน (เช่น 00-ioncube.ini) เพื่อให้ Loader เริ่มต้นทำงานก่อนส่วนขยายอื่น

4. รีสตาร์ตรันไทม์ PHP รีสตาร์ต PHP-FPM, เว็บเซิร์ฟเวอร์ของคุณ (Apache/Nginx) หรือเพียงรัน CLI ใหม่ แล้วแต่ว่าสิ่งใดเป็นตัวรันแอปพลิเคชันของคุณ กระบวนการที่ ทำงานต่อเนื่องยาวนานจะยังคงใช้การกำหนดค่าเดิมจนกว่าจะรีสตาร์ต

Verify

ยืนยันว่า Loader ทำงานอยู่ก่อนที่คุณจะลองโหลด NextPDF

อันดับแรก ให้ตรวจสอบแบนเนอร์เวอร์ชัน PHP เมื่อ Loader ถูกติดตั้ง php -v จะ เพิ่มบรรทัดที่ระบุชื่อ Loader นั้น:

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 premium โหลดผ่าน autoloader ของ 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 และ คลาส premium โหลดได้ แสดงว่า Loader ถูกตั้งค่าอย่างถูกต้อง

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

ionCube ใช้โมเดลการให้สิทธิ์การใช้งานที่เรียบง่าย คือ โค้ดที่เข้ารหัสจะตรวจหา ไฟล์ สิทธิ์การใช้งาน ในขณะรันไทม์ และจะปฏิเสธการทำงานเมื่อไฟล์หายไป อ่านไม่ได้ หรือหมดอายุ ซึ่งใช้กับ บิลด์ Pro แบบชำระเงินที่เข้ารหัสด้วย ionCube สำหรับบิลด์นี้ คุณต้องวางไฟล์สิทธิ์การใช้งานที่ได้รับจากการซื้อไว้ในตำแหน่งที่รันไทม์ค้นหาได้

กลไกไฟล์สิทธิ์การใช้งานของ ionCube นี้ใช้เฉพาะกับบิลด์ที่เข้ารหัสด้วย ionCube เท่านั้น การส่งมอบ NextPDF Enterprise official ไม่ได้ถูกสันนิษฐานว่าเข้ารหัสด้วย ionCube ในที่นี้ การบรรจุแพ็กเกจและการจัดการสิทธิ์การใช้งานของ Enterprise อยู่ภายใต้ข้อกำหนดสิทธิ์การใช้งานของคุณ ดู Licensing and activation

พาธที่แน่นอนขึ้นอยู่กับสภาพแวดล้อม ดังนั้นให้คงไว้แบบทั่วไปดังนี้:

• วางไฟล์สิทธิ์การใช้งานไว้ในตำแหน่งที่คำแนะนำการส่งมอบ NextPDF ของคุณ ระบุไว้ โดยทั่วไปคือข้างๆ แพ็กเกจที่เข้ารหัส หรือในไดเรกทอรีที่ แอปพลิเคชันอ่านได้ ตรวจสอบให้แน่ใจว่าผู้ใช้ของโปรเซส PHP มีสิทธิ์อ่านไฟล์นั้น
• อย่าเปลี่ยนชื่อไฟล์เว้นแต่คำแนะนำของคุณจะระบุให้ทำ เพราะ loader จะค้นหา ชื่อที่ระบุไว้เฉพาะ
• ใน container และในการนำไปใช้งานแบบอ่านอย่างเดียว ให้ mount หรือคัดลอกไฟล์สิทธิ์การใช้งาน เข้าไปใน image หรือพาธที่เขียนและอ่านได้ซึ่งรันไทม์มองเห็น (ดู Docker and containers)

ไฟล์สิทธิ์การใช้งานควบคุมการเปิดใช้งานในระดับรันไทม์ ซึ่งแยกจากสิทธิ์การใช้งานในระดับ แอปพลิเคชันที่เลือกรุ่นและฟีเจอร์ของคุณ สำหรับข้อกำหนด ระยะเวลา และสิ่งที่การสมัครสมาชิก ของคุณให้สิทธิ์ ดู Licensing and activation และข้อตกลงสิทธิ์การใช้งานของคุณ หน้านี้ไม่ได้กำหนดข้อกำหนดสิทธิ์การใช้งาน

Troubleshooting

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

Loader ไม่ทำงานในรันไทม์ที่รันโค้ด หรือพาธไม่ถูกต้อง ให้ตรวจสอบอีกครั้งว่าบรรทัด zend_extension ชี้ไปยังไฟล์ที่มีอยู่จริงด้วยพาธ แบบสัมบูรณ์ ว่าคุณได้รีสตาร์ตรันไทม์แล้ว และว่าคุณยืนยันรันไทม์ เดียวกัน (CLI หรือ FPM) ด้วย php -v / phpinfo() ข้อความ Failed loading มักหมายความว่า ไฟล์มีอยู่แต่ไม่ตรงกับบิลด์ PHP (ดูข้อถัดไป)

PHP version, NTS/ZTS, or architecture mismatch

Loader ที่สร้างขึ้นสำหรับเวอร์ชัน PHP, โหมด thread-safety หรือสถาปัตยกรรมที่ต่างกัน จะโหลดไม่ได้ ให้ยืนยัน PHP Version, Thread Safety และ Architecture จาก php -i แล้วติดตั้งไฟล์ Loader สำหรับ PHP 8.4 ที่ตรงกับ NTS/ZTS และ จำนวนบิตที่ตรงกัน คำลงท้าย 8.4 เทียบกับ 8.4_ts (หรือ _ts.dll) คือ ตัวเลือก thread-safety การใช้ผิดตัวคือความผิดพลาดที่เกิดบ่อย

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 จะโหลด php.ini คนละไฟล์สำหรับ CLI กับสำหรับ PHP-FPM หรือ mod_php การกำหนดค่าเฉพาะ CLI จะทำให้รันไทม์เว็บไม่มี Loader (หรือ ในทางกลับกัน) ให้รัน php --ini เพื่อดูว่า CLI ใช้ไฟล์ใด และตรวจสอบบรรทัด Loaded Configuration File ในผลลัพธ์ของเว็บ phpinfo() ให้เพิ่มบรรทัด zend_extension ไปยัง ทุก php.ini ที่รัน NextPDF และรีสตาร์ตแต่ละ รันไทม์

License file not found or expired

สำหรับบิลด์ Pro แบบชำระเงินที่เข้ารหัสด้วย ionCube ไฟล์สิทธิ์การใช้งานที่หายไป อ่านไม่ได้ หรือหมดอายุ จะหยุดไม่ให้โค้ดที่เข้ารหัสทำงาน ให้ยืนยันว่าไฟล์อยู่ใน ตำแหน่งที่คาดไว้ ว่าผู้ใช้ของโปรเซส PHP อ่านได้ และว่าไฟล์ยังไม่ หมดอายุ สำหรับคำถามเรื่องการต่ออายุและระยะเวลา ดู Licensing and activation และข้อตกลงสิทธิ์การใช้งานของคุณ

OPcache interactions

OPcache แคชสคริปต์ที่คอมไพล์แล้ว แต่ไฟล์ที่เข้ารหัสด้วย ionCube จะถูกถอดรหัสโดย Loader ในขณะรันไทม์ หากคุณเปลี่ยน Loader หรือการกำหนดค่าของมันแล้วรันไทม์ ยังคงทำงานเสมือนว่าไม่มี Loader ให้รีสตาร์ตรันไทม์ PHP (ซึ่งจะล้าง OPcache) แทนการพึ่งพา hot reload ให้คง ionCube zend_extension ลงทะเบียนไว้ เพื่อให้โหลดก่อน OPcache ทั้งสองอยู่ร่วมกันได้ และ php -v ควรแสดงทั้งคู่

Docker and containers

ในการนำไปใช้งานแบบ container ให้ติดตั้ง Loader ใน image และตรวจสอบ ให้แน่ใจว่ามันตรงกับบิลด์ PHP ของ container ไม่ใช่ของโฮสต์ของคุณ base image จะกำหนดเวอร์ชัน PHP, OS, สถาปัตยกรรม และโหมด thread-safety ไว้ตายตัว ดังนั้นให้ดาวน์โหลด Loader bundle สำหรับค่าเหล่านั้น

การสร้าง image โดยทั่วไป:

1. เริ่มจาก base image ของ PHP 8.4 (สังเกตว่าเป็น NTS หรือ ZTS โดย แท็ก official php:8.4-cli / 8.4-fpm / 8.4-apache เป็น NTS ส่วนแท็ก ที่มี zts เป็น thread-safe ให้เลือก Loader ให้ตรงกัน)
2. เพิ่มไฟล์ ionCube Loader ที่ตรงกันลงใน extension_dir ของ image
3. เขียนบรรทัด zend_extension=... ลงใน php.ini ของ image (หรือ include แบบ conf.d)
4. สำหรับบิลด์ Pro แบบชำระเงินที่เข้ารหัสด้วย ionCube ให้จัดเตรียมไฟล์สิทธิ์การใช้งานโดยคัดลอก เข้าไปใน image หรือ mount เข้าไปในขณะรันไทม์ในพาธที่ container อ่านได้

เนื่องจาก Loader ถูกสร้างไว้ใน image แล้ว container เดียวกันจึงทำงานเหมือนกัน ทุกที่ หากภายหลังคุณอัปเกรด PHP ของ base image ให้เปลี่ยนไฟล์ Loader ด้วยบิลด์ที่ตรงกับรันไทม์ใหม่

See also

• Licensing and activation
• NextPDF Premium
• Choose your path