رفع خطای libclntsh.so.12.1 هنگام بارگذاری افزونه PDO_OCI در PHP Selector

مقدمه

در محیط میزبانی تحت سیستم CloudLinux OS با ابزار PHP Selector، امکان استفاده از افزونه‌های ارتباط با پایگاه داده PDO_OCI یا OCI8 برای اتصال به پایگاه داده Oracle Instant Client فراهم شده است. با این حال، یکی از خطاهای متداول که هنگام فعال‌سازی این افزونه‌ها وقوع می‌یابد، پیام زیر است:

PHP Warning: PHP Startup: Unable to load dynamic library ‘pdo_oci.so’ (… libclntsh.so.12.1: cannot open shared object file: No such file or directory) …

این خطا نشان می‌دهد که کتابخانه‌ی اشتراکی libclntsh.so.12.1 در مسیر قابل دسترسی برای PHP پیدا نشده است. در این مقاله، ابتدا مشکل را تشریح می‌کنیم، سپس راه‌حل گام‌به‌گام طبق مستندات CloudLinux به فارسی ارایه می‌شود و در نهایت نکات تکمیلی برای پیشگیری و رفع کامل آن آورده شده است.

تشریح مشکل

• هنگامی که PDO_OCI یا OCI8 فعال می‌شوند، PHP تلاش می‌کند فایل ماژول pdo_oci.so را بارگذاری کند. در این مسیر، افزونه به کتابخانه‌ی Oracle – یعنی libclntsh.so.12.1 – وابسته است. CloudLinux+1
• اگر این کتابخانه نصب نشده باشد یا در مسیر‌های جستجوی سیستم نباشد، خطای «cannot open shared object file» نمایش داده می‌شود. CloudLinux
• در محیط CloudLinux با PHP Selector، ممکن است افزونه فعال شود اما کتابخانه‌ی Instant Client مربوطه نصب یا پیکربندی نشده باشد، در نتیجه بارگذاری موفق نخواهد بود.

مراحل رفع مشکل

طبق مستندات رسمی CloudLinux، این مراحل را دنبال کنید:

دانلود Oracle Instant Client نسخه مناسب
به صفحه دانلود Oracle Instant Client مراجعه کنید و نسخه‌ای که مورد نیاز است (در این مثال نسخه ۱۲.۱) را دانلود نمایید.
توجه: الزامی نیست جدیدترین نسخه باشد؛ مهم این است که نسخه‌ی کتابخانه‌ی مورد انتظار وجود داشته باشد.

نصب بسته کتابخانه‌های Instant Client
با استفاده از مدیر بسته (مثلاً rpm) بسته‌ای که شامل libclntsh.so.12.1 است را نصب کنید. مثال:

rpm -ihv oracle-instantclient12.1-basic-12.1.0.2.0-1.x86_64.rpm

یافتن مسیر دقیق کتابخانه
پس از نصب، مسیر دقیق فایل را با دستور find بیابید، مثلاً:

find / -name libclntsh.so.12.1 2>/dev/null

ممکن است مسیر چیزی مانند /usr/lib/oracle/21/client64/lib/libclntsh.so.12.1 باشد. CloudLinux

تنظیم مسیر برای linker دینامیک
الف) متغیر محیطی LD_LIBRARY_PATH را تنظیم کنید:

export LD_LIBRARY_PATH=/usr/lib/oracle/21/client64/lib:/usr/lib/oracle/21/client64/lib/libclntsh.so.12.1

ب) یک فایل در مسیر /etc/ld.so.conf.d/ بسازید یا مسیر را به آن اضافه کنید:

echo "/usr/lib/oracle/21/client64/lib" > /etc/ld.so.conf.d/oracle-instantclient.conf
ldconfig

این اقدامات باعث می‌شود لینک‌دهنده‌ی دینامیک بتواند کتابخانه‌ی مورد نیاز را شناسایی کند. CloudLinux

در صورت نداشتن نسخه ۱۲.۱، استفاده از نسخه جدیدتر و ایجاد لینک سمبولیک
اگر نسخه ۱۲.۱ پیدا نشد، می‌توانید نسخه جدیدتر (مثلاً ۲۱) را نصب کنید و سپس یک لینک سمبولیک برای libclntsh.so.12.1 به نسخه جدید ایجاد نمایید:

yum remove oracle-instantclient12.1-basic
yum install oracle-instantclient-basic-21.1.0.0.0-1.x86_64.rpm oracle-instantclient-devel-21.1.0.0.0-1.x86_64.rpm
cd /usr/lib/oracle/12.1/client64/lib/
ln -s /usr/lib/oracle/21/client64/lib/libclntsh.so.12.1 .

پس از آن افزونه را تست کنید. CloudLinux

تست بارگذاری افزونه برای نسخه‌های مختلف PHP
برای اطمینان از اینکه pdo_oci.so برای نسخه‌های مختلف PHP به درستی بارگذاری شده است، می‌توانید از دستوری مانند زیر استفاده کنید:

for i in 52 53 54 55 56 70 71 72 73 74 80 81 82 ; do
  echo -n "PHP $i : "
  /opt/cpanel/ea-php${i}/root/usr/bin/php -dextension=pdo_oci.so -i | grep -i -E "^PDO drivers"
done

اگر افزونه بدون خطا بارگذاری شود، خروجی مناسب را خواهید دید.

نکات تکمیلی و هشدارها

• نصب Oracle Instant Client ممکن است مستلزم قبول شرایط لایسنس Oracle باشد؛ در محیط میزبانی اشتراکی، این موضوع را رعایت کنید.
• مسیرهای client64/lib و نسخه‌ها ممکن است در توزیع‌های مختلف لینوکس متفاوت باشند؛ همیشه مسیر دقیق را بررسی کنید.
• پس از انجام مراحل بالا، ممکن است نیاز به ری‌استارت سرویس‌های PHP-FPM یا وب‌سرور (Apache/Nginx) باشد تا تنظیمات جدید اعمال شود.
• اگر از محیط‌هایی مانند CageFS یا سایر محیط‌های محدودسازی کاربران استفاده می‌کنید، مطمئن شوید مسیر کتابخانه‌ها برای کاربر PHP قابل دسترسی است.

جمع‌بندی

اگر هنگام فعال‌سازی افزونه PDO_OCI در PHP Selector با خطایی مانند libclntsh.so.12.1: cannot open shared object مواجه شدید، مراحل زیر را دنبال کنید:

1. نسخه مناسب Oracle Instant Client را نصب کنید.
2. مسیر کتابخانه libclntsh.so.12.1 را پیدا و تنظیم کنید.
3. متغیرهای محیطی و فایل پیکربندی linker را به‌روز کنید.
4. در صورت لزوم، نسخه جدیدتر نصب کرده و لینک سمبولیک ایجاد کنید.
5. بارگذاری افزونه را برای نسخه‌های PHP تست نمایید.

با انجام این مراحل، افزونه PDO_OCI (و در برخی موارد OCI8) در محیط CloudLinux با PHP Selector بدون خطا فعال خواهد شد.