Как загрузить сторонние 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, архитектурой (Intel или Apple Silicon) и опциями компиляции (NTS/ZTS) из вашей установки ServBay.

Важно: совместимость архитектуры критична

ServBay предоставляет нативные PHP-пакеты как для Intel (x86_64), так и для Apple Silicon (ARM64, например, чипы M1/M2/M3/M4). Загружая файл расширения .so, проверьте, что архитектура файла совпадает с архитектурой соответствующего PHP-пакета ServBay.

Файлы разных архитектур несовместимы — несовпадение приведёт к сбоям в запуске или аварийному завершению работы 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 # Apple Silicon ARM64

   или

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Intel x86_64

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. Для macOS ARM64 (чипы серии Apple Silicon M) скачайте версию 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. Определите, где находится папка расширений (extension_dir) для выбранной версии PHP. В ServBay расширения обычно хранятся по определённому пути, который зависит от директории установки, версии PHP и опций сборки.

   Надежный способ узнать путь — через терминал:

   Откройте Terminal и выполните (замените /Applications/ServBay/package/php/8.3/current/bin/php на ваш путь к нужной версии 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. С помощью команды cd перейдите в папку загрузки файла .tar.gz (обычно это ~/Downloads):

   cd ~/Downloads

3. Распакуйте архив:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Появится новая папка ioncube в текущем каталоге.

4. Перейдите в директорию ioncube:

   cd ioncube

5. Внутри вы увидите файлы .so для разных версий PHP, например, ioncube_loader_dar_8.3.so. Найдите файл, соответствующий вашей целевой версии PHP (см. шаг 2).

6. Скопируйте этот файл в определённую ранее папку расширений. Например, если директория назначения /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ для 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/

   • Обязательно укажите в команде путь, который вы определили в шаге 2 (php -i).
   • Убедитесь, что копируете файл, полностью соответствующий нужной версии и архитектуре (см. раздел с проверкой совместимости).

Шаг 4: Настройка PHP в ServBay

1. Вернитесь в интерфейс приложения ServBay.

2. В левой панели выберите Языки (Languages), затем кликните нужную версию PHP в правом списке (например, PHP 8.3).

3. Во вкладке справа выберите PHP.

4. Пролистайте вниз до текстового поля Additional Parameters (Дополнительные параметры).

5. Добавьте следующую строку для подключения ionCube Loader:

   zend_extension = ioncube_loader_dar_8.3.so

   • Важно! Замените ioncube_loader_dar_8.3.so на фактическое имя скопированного файла.
   • Используйте директиву zend_extension, а не extension, так как ionCube Loader — это Zend-расширение.
   • Путь не нужен, если файл уже лежит в extension_dir — достаточно имени файла.
   • Если в этом поле уже есть другие параметры, добавьте новую строку.

   (Скриншот примерный — внешний вид приложения может отличаться в зависимости от версии)

6. Нажмите Save в правом нижнем углу для сохранения изменений.

Шаг 5: Перезапуск PHP-сервиса

После нажатия кнопки Save ServBay автоматически обнаружит изменение настроек и попытается плавно перезапустить все соответствующие сервисы (включая PHP). В большинстве случаев дополнительные действия не требуются.

Шаг 6: Проверка успешной загрузки

Проверьте, подключён ли ionCube Loader одним из двух способов:

1. Через командную строку:

   • Откройте Terminal.

   • Выполните команду на вывод php-модулей (замените путь на свой):

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

     При успешной загрузке увидите строку ionCube Loader.

   • Или проверьте версию PHP, где после информации о Zend Engine будет указан ionCube Loader:

     /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():

   • В корневой директории вашего сайта (например, /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: Убедитесь, что файл .so размещён именно в реальном extension_dir нужной версии PHP. Точный путь всегда можно получить через php -i | grep extension_dir.
• Ошибка в конфигурации: В поле Additional Parameters указывайте корректную директиву. Для Zend-расширений — zend_extension = filename.so, для обычных — extension = filename.so. Имя файла должно полностью совпадать с размещённым в папке расширений (учитывая регистр).
• Проблемы с правами доступа: Проверьте, что пользователь, под которым работает ServBay (обычно ваш пользователь macOS), имеет права на чтение файла расширения и каталога. Как правило, при копировании проблем не возникает, но если вы вручную меняли права — проверьте их.
• ServBay не перезапущен: Хотя перезапуск сервисов происходит автоматически, если изменения не применились — попробуйте вручную остановить и перезапустить сервис PHP в интерфейсе ServBay или перезапустите само приложение.
• В phpinfo() нет информации: Проверьте, что обращаетесь к той версии PHP под управлением ServBay, к которой подключали расширение, и к корректному вебсайту. При работе с несколькими версиями PHP и сайтами легко ошибиться с окружением.

Итоги

Следуя приведённой пошаговой инструкции, вы сможете успешно загрузить в ServBay для выбранной версии PHP ionCube Loader или другое стороннее расширение в формате .so. Ключевые моменты: точно определить целевую версию PHP, узнать действительный путь для расширений (extension_dir), поместить совместимый файл расширения в этот каталог, а в разделе Additional Parameters интерфейса ServBay прописать верную директиву (zend_extension или extension). В случае ошибок обязательно обратитесь к разделу диагностики, особое внимание уделяя архитектурной совместимости и корректности путей к файлам.