رفع خطای undefined symbol در ماژول zip.so در CloudLinux

مقدمه

در سیستم‌عامل CloudLinux OS با استفاده از نسخه‌های alt-PHP (به ویژه نسخه ۸.۰ یا ۸.۱) ممکن است هنگام تلاش برای اجرای وب‌سایت یا سرویس‌های PHP با خطایی مواجه شوید که از طرف ماژول زیپ (zip extension) صادر شده است. پیام خطا مشابه زیر خواهد بود:

symbol lookup error: /opt/alt/php81/usr/lib64/php/modules/zip.so: undefined symbol: zip_compression_method_supported

این خطا معمولاً باعث می‌شود صفحات وب بارگذاری نشوند، سرویس ۵۰۳ ارائه شود، یا رابط کاربری «PHP Selector» کاربر نتواند صحیح نسخه PHP یا ماژول‌ها را نمایش دهد.
مقاله رسمی به تشریح این مشکل و راه‌حل آن پرداخته است. cloudlinux.zendesk.com

شرح مشکل

در لاگ وب‌سرور یا سرویس PHP‌ ممکن است چنین پیام‌هایی مشاهده کنید:

• در فایل‌هایی مثل /etc/apache2/logs/stderr.log یا مشابه آن پیام زیر دیده می‌شود:

symbol lookup error: /opt/alt/php81/usr/lib64/php/modules/zip.so: undefined symbol: zip_compression_method_supported

method_supported
استفاده از PHP Selector از طریق رابط کاربری نیز ممکن است با خطا مواجه شود.
به‌عبارت دیگر، PHP نمی‌تواند ماژول zip.so را به‌درستی بارگذاری کند زیرا نماد (symbol) مورد نیاز zip_compression_method_supported پیدا نشده است. این خطا غالباً نتیجهٔ شکاف بین نسخه‌ی کتابخانه‌های زیرساختی (مانند libzip) با ماژول زیپ است.
محیط تحت تأثیر

سیستم‌عامل: CloudLinux OS

نسخه‌های alt-PHP: ۸.۰، ۸.۱

ماژول مرتبط: zip (۰‌پسوند .so)

بستهٔ درگیر: alt-libzip و ماژول zip داخل alt-PHP
cloudlinux.zendesk.com

علت خطا

مطابق مقاله رسمی CloudLinux، علت اصلی این خطا به صورت زیر است:
«Install or update alt-libzip package to the latest version.»
cloudlinux.zendesk.com
به زبان ساده، ماژول zip برای نسخهٔ alt-PHP نیازمند کتابخانهٔ libzip با نسخه‌ای مشخص است که نماد zip_compression_method_supported را فراهم می‌کند. اگر نسخهٔ libzip نصب‌شده روی سرور قدیمی باشد یا با نسخهٔ ماژول زیپ تطابق نداشته باشد، نماد مورد نیاز پیدا نمی‌شود و PHP هنگام بارگذاری ماژول با خطا مواجه می‌شود.
راه‌حل

گام ۱: بررسی نسخهٔ libzip

ابتدا وارد ترمینال SSH شوید و بررسی کنید نسخهٔ بستهٔ alt-libzip نصب شده چیست:

rpm -qa | grep alt-libzip

اگر نسخهٔ آن قدیمی است یا نصب نشده است، به گام بعدی بروید.

گام ۲: به‌روزرسانی بستهٔ alt-libzip

اجرای دستور زیر برای به‌روزرسانی بستهٔ libzip:

yum update alt-libzip -y

یا اگر نسخهٔ PHP خاصی را هدف گرفته‌اید:

yum update alt-libzip --enablerepo=cloudlinux-x86_64-server

پس از اتمام به‌روزرسانی، بررسی کنید که نسخهٔ جدید نصب شده است.

گام ۳: بررسی ماژول zip برای alt-PHP

پس از به‌روزرسانی libzip، سرویس PHP را ری‌استارت کنید یا آن نسخهٔ alt-PHP را مجدداً بارگذاری کنید. سپس بررسی نمایید:

php -v
php -m | grep zip

اگر ماژول zip در خروجی دیده شد و خطا در لاگ‌ها ظاهر نمی‌شود، مشکل رفع شده است.

گام ۴: ری‌استارت سرویس وب‌سرور

service httpd restart
# OR LiteSpeed
service lsws restart

نکات تکمیلی

• اگر شما چند نسخهٔ alt-PHP روی سرور دارید (مثلاً alt-php80، alt-php81)، لازم است تنظیمات و به‌روزرسانی‌ها را برای همه نسخه‌ها به انجام برسانید.
• در سرورهایی که از CageFS یا LVE استفاده می‌کنند، پس از به‌روزرسانی libzip و zip ماژول، ممکن است نیاز به به‌روزرسانی یا بازسازی قالب CageFS باشد تا ماژول به‌صورت کامل برای کاربران فعال شود.
• اگر بعد از به‌روزرسانی هنوز خطا ادامه دارد، بررسی کنید که فایل /opt/alt/php81/usr/lib64/php/modules/zip.so وجود دارد، حجم آن مطلوب است (بیشتر از صفر) و معماری فایل مطابق با سیستم شما است. همچنین مطمئن شوید که مسیر فایل با تنظیمات ini ماژول مطابقت دارد.

جمع‌بندی

خطای

symbol lookup error: /opt/alt/php81/usr/lib64/php/modules/zip.so: undefined symbol: zip_compression_method_supported
نشانهٔ این است که کتابخانهٔ libzip نسخهٔ مناسب برای ماژول zip در alt-PHP نصب یا بارگذاری نشده است.
با به‌روزرسانی بستهٔ alt-libzip به نسخهٔ مناسب و ری‌استارت کردن سرویس PHP و وب‌سرور، می‌توان این مشکل را به‌سادگی و با اطمینان برطرف کرد.