مقدمه

یکی از خطاهای رایج هنگام استفاده از Redis Extension در PHP، خطای زیر است:

PHP Warning: PHP Startup: Unable to load dynamic library 'redis.so'

در برخی سرورها این خطا با پیام‌هایی مانند:

undefined symbol: igbinary_serialize

یا:

undefined symbol: php_msgpack_serialize

نمایش داده می‌شود.

این خطا لزوماً به معنی خراب بودن Redis Server یا نصب نبودن redis.so نیست. در محیط‌هایی مانند CloudLinux و Alt-PHP، Redis می‌تواند به Extensionهای دیگری مانند igbinary و msgpack وابسته باشد و اگر این Extensionها با ترتیب نادرست Load شوند، PHP هنگام Startup قادر به Load کردن Redis نخواهد بود.

در این آموزش، یک نمونه واقعی از این خطا را بررسی می‌کنیم، علت آن را پیدا می‌کنیم و بدون حذف Packageها یا ایجاد تغییرات غیرضروری روی سایر کاربران، Configuration صحیح را اعمال می‌کنیم.

سناریوی خطا

فرض کنید در Error Log یک سایت WordPress با PHP 8.4 با خطای زیر مواجه شده‌ایم:

PHP Warning: PHP Startup: Unable to load dynamic library 'redis.so'
(tried: /opt/alt/php84/usr/lib64/php/modules/redis.so
(/opt/alt/php84/usr/lib64/php/modules/redis.so:
undefined symbol: igbinary_serialize))

مسیر Extension نشان می‌دهد که Redis مربوط به Alt-PHP 8.4 است:

/opt/alt/php84/usr/lib64/php/modules/redis.so

بنابراین اولین کار این است که مشخص کنیم مشکل از Package، Configuration یا ترتیب Load شدن Extensionها است.

بررسی نسخه PHP

ابتدا نسخه PHP موردنظر را بررسی کنید:

/opt/alt/php84/usr/bin/php -v

در این نمونه نسخه PHP به شکل زیر بود:

PHP 8.4.25

همچنین مسیر Extensionها را بررسی کنید:

/opt/alt/php84/usr/bin/php -i | grep extension_dir

خروجی مورد انتظار:

extension_dir => /opt/alt/php84/usr/lib64/php/modules

بررسی نصب بودن Redis

برای بررسی Package مربوط به Redis:

rpm -qa | grep -E 'alt-php84.*redis'

در این نمونه Package زیر نصب بود:

alt-php84-pecl-redis-6.3.0-13.el9.x86_64

همچنین می‌توان نسخه PECL Redis را بررسی کرد:

/opt/alt/php84/usr/bin/pecl info redis

در این مورد Redis نسخه:

6.3.0

نصب شده بود.

بنابراین مشخص شد که Redis نصب است و مشکل صرفاً نبودن Package نیست.

بررسی Extensionهای وابسته Redis

Redis در این Configuration به Extensionهای دیگری نیز وابسته است.

برای بررسی igbinary:

ls -l /opt/alt/php84/usr/lib64/php/modules/igbinary.so

برای msgpack:

ls -l /opt/alt/php84/usr/lib64/php/modules/msgpack.so

و برای Redis:

ls -l /opt/alt/php84/usr/lib64/php/modules/redis.so

بررسی Symbol مربوط به igbinary

خطای اصلی ما این بود:

undefined symbol: igbinary_serialize

برای بررسی اینکه این Symbol واقعاً در igbinary.so وجود دارد یا خیر:

nm -D /opt/alt/php84/usr/lib64/php/modules/igbinary.so | grep igbinary_serialize

اگر خروجی مشابه زیر باشد:

000000000000e650 T igbinary_serialize
000000000000e330 T igbinary_serialize_ex
000000000000e660 T zif_igbinary_serialize

یعنی igbinary.so سالم است و Symbol موردنیاز را Export می‌کند.

در نتیجه مشکل از خراب یا ناقص بودن igbinary.so نیست.

بررسی وابستگی Redis به igbinary

برای بررسی وابستگی Redis:

nm -D /opt/alt/php84/usr/lib64/php/modules/redis.so | grep -E "igbinary|redis_module_entry"

اگر خروجی مشابه زیر باشد:

                 U igbinary_serialize
                 U igbinary_unserialize
00000000000f0000 D redis_module_entry

حرف U نشان می‌دهد که Redis این Symbolها را از Extension دیگری انتظار دارد.

در نتیجه:

redis.so
    ↓
نیاز به igbinary_serialize
    ↓
igbinary.so باید قبل از Redis Load شود

بررسی وابستگی Redis به MessagePack

در بررسی دقیق‌تر ممکن است پس از Load کردن igbinary با خطای دیگری مواجه شوید:

undefined symbol: php_msgpack_serialize

این پیام نشان می‌دهد Redis علاوه بر igbinary به msgpack نیز وابستگی دارد.

برای بررسی Symbolهای MessagePack:

nm -D /opt/alt/php84/usr/lib64/php/modules/msgpack.so \
| grep -E "php_msgpack_(serialize|unserialize)"

خروجی صحیح باید شامل مواردی مانند:

php_msgpack_serialize
php_msgpack_unserialize

باشد.

بررسی ترتیب صحیح Load شدن Extensionها

در Configuration صحیح، Extensionها باید به ترتیب مناسب Load شوند:

msgpack
   ↓
igbinary
   ↓
redis

یک Configuration مناسب می‌تواند به شکل زیر باشد:

extension=msgpack.so
extension=igbinary.so
extension=redis.so

این ترتیب اهمیت دارد؛ زیرا Redis هنگام Load شدن باید Symbolهای موردنیاز خود را قبلاً در محیط PHP داشته باشد.

تست بدون تغییر Configuration

قبل از هرگونه تغییر در Production بهتر است Configuration را به‌صورت موقت تست کنیم.

برای PHP 8.4:

/opt/alt/php84/usr/bin/php -n \
-d extension=msgpack.so \
-d extension=igbinary.so \
-d extension=redis.so \
-m 2>&1

در این دستور گزینه:

-n

باعث می‌شود PHP فایل php.ini را نخواند و Extensionها فقط از طریق گزینه‌های -d Load شوند.

اگر خروجی شامل موارد زیر باشد:

igbinary
msgpack
redis

یعنی Packageها و Binaryهای Extensionها سالم هستند و ترتیب صحیح Load شدن نیز مشکل را برطرف می‌کند.

برای تست مستقیم وضعیت Extensionها:

/opt/alt/php84/usr/bin/php -n \
-d extension=msgpack.so \
-d extension=igbinary.so \
-d extension=redis.so \
-r 'echo "msgpack=", extension_loaded("msgpack") ? "ON" : "OFF", PHP_EOL, "igbinary=", extension_loaded("igbinary") ? "ON" : "OFF", PHP_EOL, "redis=", extension_loaded("redis") ? "ON" : "OFF", PHP_EOL;'

خروجی صحیح:

msgpack=ON
igbinary=ON
redis=ON

این تست یکی از مهم‌ترین مراحل عیب‌یابی است، زیرا مشخص می‌کند مشکل از خود Packageها نیست.

بررسی CloudLinux PHP Selector

در سرورهای CloudLinux، Extensionها ممکن است توسط PHP Selector برای هر User مدیریت شوند.

برای مشاهده Extensionهای Global مربوط به PHP 8.4:

selectorctl -i php -v 8.4 -G

اگر موارد زیر با + نمایش داده شوند:

+ igbinary
+ msgpack
+ redis

یعنی این Extensionها در PHP Selector فعال هستند.

بررسی Extensionهای یک User

برای بررسی User مشخص:

selectorctl -i php -v 8.4 -u billionr -g

در این نمونه، User موردنظر:

billionr

بود و Extensionهای زیر برای آن فعال بودند:

igbinary
msgpack
redis

بنابراین مشخص شد که مشکل از غیرفعال بودن Redis در PHP Selector نیست.

بررسی Configuration واقعی User

یکی از مهم‌ترین مراحل، بررسی Configuration واقعی User است.

برای User موردنظر:

su -s /bin/bash billionr -c '/opt/alt/php84/usr/bin/php --ini'

ممکن است خروجی مشابه زیر باشد:

Configuration File (php.ini) Path: /opt/alt/php84/etc
Loaded Configuration File: /opt/alt/php84/etc/php.ini
Scan for additional .ini files in: /opt/alt/php84/link/conf
Additional .ini files parsed:
 /opt/alt/php84/link/conf/alt_php.ini
 /opt/alt/php84/link/conf/clos_ssa.ini

در اینجا باید فایل alt_php.ini را بررسی کرد:

su -s /bin/bash billionr -c \
'cat /opt/alt/php84/link/conf/alt_php.ini'

در Configuration صحیح User ممکن است موارد زیر را مشاهده کنید:

;---igbinary---
extension=igbinary.so

;---msgpack---
extension=msgpack.so

;---redis---
extension=redis.so

بنابراین PHP Selector Configuration صحیح را برای User تولید کرده است.

پیدا کردن Configuration اشتباه

در نمونه مورد بررسی، مشکل در فایل Global زیر قرار داشت:

/opt/alt/php84/etc/php.ini

در این فایل خط زیر وجود داشت:

extension=redis.so

این خط باعث می‌شد Redis قبل از اینکه igbinary و msgpack توسط Configuration مربوط به User Load شوند، مستقیماً توسط php.ini Load شود.

در نتیجه ساختار Load شدن به این شکل بود:

php.ini
   ↓
redis.so
   ↓
igbinary هنوز Load نشده
   ↓
undefined symbol: igbinary_serialize

بعد PHP به Configuration مربوط به User می‌رسید و Extensionهای زیر را Load می‌کرد:

igbinary
msgpack
redis

به همین دلیل ممکن بود دستور:

php -m

در نهایت Redis را نشان دهد، اما همچنان در ابتدای Startup یک Warning ثبت شده باشد.

بررسی Configuration قبل از تغییر

قبل از هر تغییری در Production از فایل Configuration نسخه پشتیبان بگیرید:

cp -a /opt/alt/php84/etc/php.ini \
/opt/alt/php84/etc/php.ini.bak.$(date +%F-%H%M%S)

سپس بررسی کنید Redis در php.ini فعال است:

grep -nE "redis|igbinary|msgpack" \
/opt/alt/php84/etc/php.ini

اگر خروجی مشابه زیر بود:

1632:extension=redis.so

باید بررسی کنید که آیا Redis از طریق PHP Selector برای Userها نیز فعال شده است یا خیر.

رفع مشکل

اگر Redis توسط PHP Selector برای User مدیریت می‌شود، خط Global زیر:

extension=redis.so

نباید به‌صورت Global در php.ini وجود داشته باشد.

برای حذف آن از Load شدن Global، می‌توان خط را Comment کرد:

;extension=redis.so

برای این کار:

sed -i 's/^[[:space:]]*extension=redis\.so[[:space:]]*$/;extension=redis.so/' \
/opt/alt/php84/etc/php.ini

سپس بررسی کنید:

grep -nE "redis|igbinary|msgpack" \
/opt/alt/php84/etc/php.ini

باید نتیجه‌ای مشابه زیر داشته باشید:

1632:;extension=redis.so

بررسی عملکرد Redis پس از اصلاح

اکنون PHP User را بررسی کنید:

su -s /bin/bash billionr -c \
'/opt/alt/php84/usr/bin/php -m 2>&1 | grep -E "redis|igbinary|msgpack|Warning"'

خروجی صحیح:

igbinary
msgpack
redis

مهم است که در این خروجی هیچ Warning مربوط به redis.so وجود نداشته باشد.

بررسی فعال بودن Redis

برای اطمینان بیشتر:

su -s /bin/bash billionr -c \
'/opt/alt/php84/usr/bin/php -r '\''echo "Redis: ", extension_loaded("redis") ? "ON" : "OFF", PHP_EOL;'\'''

خروجی مورد انتظار:

Redis: ON

این نتیجه نشان می‌دهد که Redis همچنان برای User فعال است و فقط روش Load شدن آن اصلاح شده است.

بررسی Log پس از اصلاح

بعد از اصلاح، Error Log مربوط به سایت را بررسی کنید:

tail -n 50 /home/billionr/www/error_log

برای پیدا کردن خطاهای Redis:

grep -n "Unable to load dynamic library 'redis.so'" \
/home/billionr/www/error_log | tail

نکته مهم این است که Timestamp خطاها را بررسی کنید. وجود خطاهای قدیمی در Log به معنی ادامه داشتن مشکل نیست.

باید بررسی شود که بعد از زمان اصلاح، خطای جدیدی با همان پیام ثبت شده یا خیر.

بررسی PHP 8.2 و PHP 8.3

اگر سرور چند نسخه Alt-PHP دارد، فقط بررسی PHP 8.4 کافی نیست.

ابتدا بررسی کنید آیا Redis در php.ini نسخه‌های دیگر نیز Global فعال شده است:

grep -nE "redis|igbinary|msgpack" \
/opt/alt/php82/etc/php.ini

و:

grep -nE "redis|igbinary|msgpack" \
/opt/alt/php83/etc/php.ini

اگر در هر دو مورد خطی مانند زیر وجود داشت:

extension=redis.so

باید قبل از تغییر، بررسی شود که PHP Selector برای Userهای آن نسخه چگونه Extensionها را مدیریت می‌کند.

در محیط Production بهتر است بدون بررسی Userهای فعال، به‌صورت سراسری Extensionها را حذف یا Disable نکنید.

بررسی Packageهای Redis

برای مشاهده Packageهای مرتبط با PHP 8.4:

rpm -qa | grep -E "alt-php84.*(redis|igbinary|msgpack)"

نمونه Packageهای مرتبط:

alt-php84-pecl-msgpack
alt-php84-pecl-igbinary
alt-php84-pecl-redis

وجود این Packageها به‌تنهایی تضمین نمی‌کند Configuration صحیح باشد؛ بنابراین قبل از Reinstall کردن Packageها، ابتدا Configuration و ترتیب Load شدن Extensionها را بررسی کنید.

بررسی وابستگی‌های Library

برای بررسی Libraryهای Native مربوط به Redis:

ldd /opt/alt/php84/usr/lib64/php/modules/redis.so

اگر Libraryهای اصلی مانند:

liblz4.so
libzstd.so
libc.so

Resolve شده باشند، مشکل از Missing System Library نیست.

خطاهای مشابه

undefined symbol: igbinary_serialize

این خطا معمولاً نشان می‌دهد Redis قبل از igbinary Load شده یا Redis و igbinary از نظر Binary/API با یکدیگر سازگار نیستند.

ابتدا بررسی کنید:

nm -D /opt/alt/php84/usr/lib64/php/modules/igbinary.so \
| grep igbinary_serialize

undefined symbol: php_msgpack_serialize

این خطا نشان می‌دهد Redis به MessagePack نیاز دارد اما msgpack.so در زمان Load شدن Redis در دسترس نیست.

بررسی:

nm -D /opt/alt/php84/usr/lib64/php/modules/msgpack.so \
| grep -E "php_msgpack_(serialize|unserialize)"

Redis در php -m وجود دارد ولی Warning ثبت می‌شود

این حالت ممکن است زمانی رخ دهد که Redis یک بار در ابتدای Startup با Configuration اشتباه Load شود و بعد مجدداً از Configuration صحیح User Load شود.

در این حالت:

php -m

ممکن است در نهایت:

redis

را نشان دهد، اما Warning مربوط به Startup همچنان ثبت شده باشد.

بنابراین صرفاً وجود redis در خروجی php -m برای تشخیص کافی نیست؛ باید Warningهای Startup نیز بررسی شوند.

تفاوت Configuration Global و User در CloudLinux

در CloudLinux بهتر است Extensionهایی که از طریق PHP Selector برای Userها مدیریت می‌شوند، از همان مکانیزم مدیریت شوند.

ساختار مناسب:

PHP Global Configuration
        │
        └── php.ini

User Configuration
        │
        └── PHP Selector / alt_php.ini
                 │
                 ├── igbinary
                 ├── msgpack
                 └── redis

اگر Redis هم در php.ini و هم در Configuration User فعال شود، احتمال Load شدن آن در زمان نامناسب یا به شکل تکراری وجود دارد.

اشتباهات رایج

حذف کردن redis.so

این کار معمولاً اولین راه‌حل مناسبی نیست:

rm /opt/alt/php84/usr/lib64/php/modules/redis.so

ممکن است سایت‌های دیگری که به Redis نیاز دارند دچار مشکل شوند.

حذف Package Redis

دستورهایی مانند:

dnf remove alt-php84-pecl-redis

نباید بدون بررسی Userهای وابسته اجرا شوند.

فعال کردن فقط Redis

فعال کردن:

extension=redis.so

بدون توجه به وابستگی‌های آن می‌تواند باعث خطاهایی مانند:

undefined symbol: igbinary_serialize

یا:

undefined symbol: php_msgpack_serialize

شود.

تغییر Global Configuration بدون بررسی PHP Selector

در سرورهای CloudLinux، تغییر مستقیم php.ini ممکن است روی تعداد زیادی User اثر بگذارد.

قبل از تغییر Global Configuration بررسی کنید:

selectorctl -i php -v 8.4 -G

و برای User مشخص:

selectorctl -i php -v 8.4 -u USERNAME -g

بهترین روش برای عیب‌یابی این خطا

ترتیب پیشنهادی بررسی به این شکل است:

Error Log
   ↓
نسخه PHP
   ↓
مسیر redis.so
   ↓
Packageهای Redis / igbinary / msgpack
   ↓
بررسی Symbolها
   ↓
تست با php -n
   ↓
بررسی PHP Selector
   ↓
بررسی Configuration واقعی User
   ↓
بررسی php.ini
   ↓
اصلاح ترتیب Load
   ↓
تست PHP
   ↓
بررسی Error Log جدید

این روش از Reinstall کردن Packageها یا ایجاد تغییرات گسترده روی سرور جلوگیری می‌کند.

چک‌لیست

پس از مطالعه این مقاله باید بتوانید:

• خطای Unable to load dynamic library 'redis.so' را تحلیل کنید.
• تفاوت مشکل Redis Server و PHP Redis Extension را تشخیص دهید.
• وابستگی Redis به igbinary و msgpack را بررسی کنید.
• وجود Symbolهای موردنیاز را با nm بررسی کنید.
• وابستگی‌های Native Redis را با ldd بررسی کنید.
• Redis را با php -n به‌صورت ایزوله تست کنید.
• Extensionهای PHP را در CloudLinux PHP Selector بررسی کنید.
• Configuration واقعی یک User را بررسی کنید.
• مشکل Load شدن Redis قبل از وابستگی‌هایش را شناسایی کنید.
• از تغییرات غیرضروری Global روی سرور Production جلوگیری کنید.
• پس از اصلاح، فعال بودن Redis و عدم ثبت Warning جدید را بررسی کنید.

جمع‌بندی

خطای:

undefined symbol: igbinary_serialize

در PHP به‌تنهایی به معنی خراب بودن Redis نیست. در محیط‌های CloudLinux و Alt-PHP، Redis می‌تواند به Extensionهایی مانند igbinary و msgpack وابسته باشد و این Extensionها باید قبل از Redis در PHP Load شوند.

در سناریوی بررسی‌شده، Packageهای Redis، igbinary و msgpack سالم بودند و تست ایزوله نیز نشان داد که ترکیب زیر بدون خطا کار می‌کند:

msgpack
   ↓
igbinary
   ↓
redis

مشکل از فعال بودن redis.so به‌صورت Global در php.ini بود؛ در حالی که CloudLinux PHP Selector برای User، Configuration صحیح و وابستگی‌های Redis را به‌صورت جداگانه مدیریت می‌کرد. با خارج کردن Load اضافی Redis از Global php.ini، Redis از طریق Configuration صحیح User بارگذاری شد و خطای Startup برطرف شد.

نکته اصلی در چنین خطاهایی این است که قبل از Reinstall یا حذف Extensionها، ترتیب Load شدن Extensionها، وابستگی‌های Binary و نحوه مدیریت PHP توسط CloudLinux Selector بررسی شود.