Як підключити сторонні PHP-розширення у ServBay

ServBay — це потужне локальне середовище для веброзробки, яке вже містить багато популярних PHP-розширень «з коробки». Зазвичай користувачу достатньо просто увімкнути або налаштувати їх у меню Пакети (Packages) → Мови (Languages) → Версія PHP → Розширення.

Однак інколи розробнику необхідно підключити стороннє або власноруч скомпільоване PHP-розширення, яке відсутнє у комплекті ServBay за замовчуванням. У цьому матеріалі покроково розглянуто процес підключення такого розширення для конкретної версії PHP у ServBay на прикладі ionCube Loader. Аналогічні дії підходять і для інших Zend-розширень чи ваших власних .so файлів розширень.

Особлива примітка щодо Zend-розширень: ionCube Loader є Zend-розширенням, тобто глибше інтегрується з Zend Engine PHP. Для активації таких розширень потрібно використовувати директиву zend_extension, а не стандартну extension. Будь ласка, уважно відрізняйте й використовуйте відповідну директиву.

Передумови

• Ви вже встановили та запустили ServBay на операційній системі macOS.
• Ви маєте права адміністратора, а також доступ до системних файлів і налаштувань ServBay.
• Ви володієте базовими навичками користування Terminal у macOS.
• Ви вже отримали файл стороннього розширення PHP, зазвичай з розширенням .so, який повністю сумісний з цільовою версією PHP у ServBay, її архітектурою (Intel або Apple Silicon) та параметрами компіляції (наприклад, NTS/ZTS).

Увага: критично важлива архітектурна сумісність

ServBay пропонує нативні PHP-пакети для архітектур Intel (x86_64) та Apple Silicon (ARM64, серії M1/M2/M3/M4). При підключенні .so-файлів розширень обов’язково переконайтесь, що розширення було скомпільовано саме під ту архітектуру, яка відповідає встановленому у ServBay PHP.

Файли для різних архітектур не можна змішувати — така невідповідність призведе до неможливості запуску чи аварій PHP.

Щоб визначити архітектуру виконуваних файлів або .so-розширення, скористайтесь командою file:

1. Визначте архітектуру PHP у ServBay (замініть 8.3 на вашу версію):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   Можливий вивід:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # позначає ARM64 для Apple Silicon

   або

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # позначає x86_64 для Intel

2. Визначте архітектуру завантаженого чи скомпільованого розширення (замініть xdebug.so на файл вашого розширення):

   file xdebug.so

   Можливий вивід:

   xdebug.so: Mach-O 64-bit bundle arm64 # для Apple Silicon ARM64

   або

   xdebug.so: Mach-O 64-bit bundle x86_64 # для Intel x86_64

   Переконайтесь, що інформація про архітектуру у кроці 1 та кроці 2 повністю збігається.

Покрокова інструкція

Крок 1: Завантаження стороннього розширення (приклад — ionCube Loader)

1. Перейдіть на офіційний сайт завантаження ionCube Loader та оберіть пакет відповідно до архітектури вашого macOS. Для ARM64 (Apple Silicon) оберіть Darwin ARM64. Можна скористатися цим прикладом посилання (обов'язково перевірте офіційну сторінку щодо актуальності): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Після завантаження ви отримаєте архів .tar.gz, наприклад, ioncube_loaders_dar_arm64.tar.gz.

Крок 2: Визначення цільової версії PHP та директорії розширень у ServBay

1. Відкрийте додаток ServBay.

2. У лівому меню оберіть Пакети (Packages) → Мови (Languages).

3. У правому списку знайдіть ту версію PHP, до якої ви хочете додати ionCube Loader (наприклад, PHP 8.3). Запам’ятайте номер потрібної версії.

4. З'ясуйте директорію для розширень цільової версії PHP (extension_dir), куди потрібно розміщувати .so-файли. У ServBay це залежить від версії PHP та установки.

   Найточніше це дізнатися через Terminal:

   Відкрийте Terminal і виконайте (замінивши шлях на актуальний для вашої версії PHP):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   Результат буде схожим на:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Обов’язково збережіть цей шлях — він знадобиться далі.

Крок 3: Розпакування та розміщення Loader-файлу

1. Відкрийте Terminal.

2. Перейдіть до папки з завантаженим архівом (припустимо, це ~/Downloads):

   cd ~/Downloads

3. Розпакуйте архів:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   З’явиться нова директорія ioncube.

4. Увійдіть до розпакованої папки:

   cd ioncube

5. Тут будуть .so-файли для різних версій PHP: наприклад, ioncube_loader_dar_8.3.so. Оберіть файл, який відповідає вашій PHP-версії.

6. Скопіюйте обраний .so-файл до каталогу розширень (extension_dir), визначеного у кроці 2 (приклад для версії PHP 8.3):

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Обов’язково замініть шлях /Applications/ServBay/.../no-debug-non-zts-20230831/ на фактичний, який ви отримали після виконання php -i.
   • Перевірте, що файл точно відповідає потрібній версії PHP і його архітектура збігається із ServBay-пакетом (див. перевірку у Передумовах).

Крок 4: Налаштування PHP у ServBay

1. Поверніться до вікна додатку ServBay.

2. У лівому меню переконайтесь, що вибрано Мови (Languages), а справа відкрито потрібну версію PHP (наприклад, PHP 8.3).

3. Перейдіть до вкладки PHP у правій частині налаштувань.

4. Прокрутіть до поля Additional Parameters (Додаткові параметри).

5. Додайте у полі наступну інструкцію, де вказано файл Loader-а:

   zend_extension = ioncube_loader_dar_8.3.so

   • Важливо: Замініть ioncube_loader_dar_8.3.so на актуальну назву копійованого вами файла.
   • Використовуйте zend_extension, оскільки ionCube Loader — це Zend-розширення.
   • Шляхом тут зазначається лише ім’я файлу (повний шлях не потрібен, оскільки файл розміщено у extension_dir).
   • Якщо у цьому полі вже є інші директиви, додавайте нову з нового рядка.

   (Знімок екрана — ілюстративний приклад, інтерфейс може дещо відрізнятися залежно від версії)

6. Натисніть Save у правому нижньому куті для збереження конфігурації.

Крок 5: Перезапуск PHP-сервісу

Після натискання Save у ServBay, система автоматично визначає зміни у налаштуваннях і виконує плавний перезапуск відповідних сервісів (у тому числі PHP). Додаткових дій зазвичай не потрібно.

Крок 6: Перевірка успішності підключення

Пропонуємо два підходи для перевірки чи завантажено ionCube Loader:

1. Перевірка через командний рядок:

   • Відкрийте Terminal.

   • Виконайте команду для виведення списку завантажених модулів PHP (указуючи повний шлях до потрібної версії PHP):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     Якщо підключення пройшло успішно, з’явиться рядок на кшталт ionCube Loader.

   • Використайте також команду php -v для перегляду інформації про версію PHP та розширення (зазвичай ionCube Loader буде відображено під інформацією про Zend Engine):

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Приклад вдалого результату (номери версій можуть відрізнятися):

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Зверніть увагу на рядок з with the ionCube PHP Loader ....

2. Перевірка через функцію phpinfo():

   • Створіть окремий PHP-файл у кореневій папці вашого сайту (наприклад, /Applications/ServBay/www/servbay.demo/ або свій шлях), назвіть його info.php.
   • Напишіть у ньому наступне:

     <?php
     phpinfo();
     ?>

   • Відкрийте цей файл у браузері, наприклад, http://servbay.demo/info.php (змініть на вашу адресу сайту).
   • У відкритій сторінці знайдіть («Пошук по сторінці» — Cmd+F або Ctrl+F) слово "ionCube". Якщо розширення підключено правильно, з’явиться окремий розділ із інформацією про ionCube Loader: версія, ліцензія тощо.

Якщо на будь-якому з етапів знаходите згадку про ionCube Loader — розширення підключено успішно.

Поширені помилки та способи їх вирішення

• PHP не стартує або аварійно завершує роботу: Найймовірніша причина — невідповідність архітектур між розширенням і PHP. Перевірте всі кроки з розділу «Передумови». Також можливі проблеми несумісності версій PHP чи параметрів компіляції.
• Невірний шлях до extension_dir: Слідкуйте, щоб копіювали файл саме у потрібну директорію, визначену командою php -i | grep extension_dir.
• Помилка у написанні директиви: У полі Additional Parameters для Zend-розширень обов’язково використовуйте zend_extension = filename.so; для звичайних — extension = filename.so. Назва файла має точно співпадати, враховуючи регістр символів.
• Проблеми з правами доступу: Перевірте, що ServBay (ваш користувач macOS) має права на читання .so-файлу і теки, у яку його скопійовано. У більшості випадків за замовчуванням проблем не виникає, але після вручну змінених прав може знадобитись корекція.
• ServBay не перезапущено: Якщо після налаштувань зміни не набули чинності — спробуйте перезапустити PHP або додаток ServBay вручну.
• Відсутня інформація у phpinfo(): Перевірте, що відкриваєте phpinfo() саме тієї версії PHP, для якої налаштовували розширення — це особливо актуально, якщо у вас кілька версій або сайтів.

Висновок

Дотримуючись цього детального посібника, ви легко підключите ionCube Loader чи будь-який інший сторонній .so-модуль PHP у вибрану версію PHP, що керується ServBay. Головне: впевнитися у правильному визначенні версії PHP, знайти коректну директорію розширень (extension_dir), скопіювати до неї сумісне розширення та додати коректну директиву (zend_extension або extension) через інтерфейс налаштувань ServBay у полі Additional Parameters. Якщо зіткнетеся із проблемами — ретельно перевірте кроки діагностики, особливо сумісність архітектури та шлях до файлів.