Компиляция и установка пользовательских PHP модулей в ServBay (macOS)

ServBay — это мощная локальная среда веб-разработки, специально созданная для macOS и интегрирующая широкий спектр программных компонентов для современных веб-разработчиков. В дистрибутив уже включены PHP, Node.js, Python, Go, Java, базы данных (MySQL, PostgreSQL, MongoDB), кэш (Redis), а также веб-серверы (Caddy, Nginx, Apache) и другие технологии. ServBay поддерживает несколько версий каждого пакета, что позволяет гибко переключаться между версиями под разные проекты.

Хотя ServBay уже содержит множество часто используемых PHP-модулей, иногда возникают случаи, когда необходимо самостоятельно скомпилировать и установить дополнительные модули PHP для расширения его функциональности или интеграции с конкретными сторонними сервисами.

В этом руководстве подробно описан процесс компиляции и установки пользовательских модулей PHP для вашей версии PHP в среде ServBay. В качестве примера будет продемонстрирована сборка популярных модулей — imagick (обработка изображений) и sqlsrv (драйвер для базы данных Microsoft SQL Server). Следуйте этим шагам, чтобы успешно добавить необходимые функции в PHP-окружение ServBay.

Предварительные требования

Важно!

Перед началом компиляции любого PHP-модуля самым важным шагом является запуск скрипта инициализации компиляционной среды ServBay и правильная настройка системных переменных окружения, согласно официальной документации ServBay. Именно это — фундамент для успешной сборки любых пакетов ServBay (включая PHP-модули). Если вы пропустите этот шаг или выполните его некорректно, высока вероятность последующих ошибок компиляции: команда не найдена, библиотека или заголовочный файл отсутствуют и так далее.

Скрипт инициализации настроит необходимые переменные окружения, такие как PATH (указывает на внутренние инструменты сборки ServBay), SERVBAY_PACKAGE_FULL_PATH (путь к корневому каталогу пакетов ServBay) и CPU_NUMBER (число ядер для параллельной сборки). Эти переменные критически необходимы для всех дальнейших команд компиляции.

Подробные шаги по инициализации среды смотрите в документации: Вторичная компиляция с использованием ServBay. Убедитесь, что вы полностью поняли и строго выполнили все инструкции из указанной статьи.

Перед тем как приступить к сборке модулей, обязательно удостоверьтесь, что среда компиляции ServBay успешно инициализирована, а переменные окружения корректно заданы в вашем текущем сеансе терминала.

Важность выбора версии PHP

Одной из основных особенностей ServBay является одновременная поддержка нескольких версий PHP. Это удобно для запуска нескольких проектов с разными требованиями к версии языка. Однако при компиляции расширения PHP вы должны всегда указывать точную версию PHP, для которой оно будет собрано. Инструменты phpize и php-config, которые используются для подготовки окружения и получения информации о версии, строго привязаны к конкретной сборке PHP.

• phpize: утилита для подготовки среды сборки расширения PHP. Читает config.m4 и создает скрипт configure, с которого начинается типовая сборка C/C++-программ.
• php-config: скрипт, который предоставляет полную информацию о конкретной установке PHP — флаги компилятора, директории с заголовками и библиотеками, путь для установки расширений и прочее. Скрипт configure использует его для правильной компоновки модуля с вашей версией PHP.

Поэтому при использовании любого из этих инструментов всегда указывайте их полный путь для нужной версии PHP. Например, если вы компилируете модуль для PHP 8.3 из пакета ServBay, используйте /Applications/ServBay/package/php/8.3/current/bin/phpize и /Applications/ServBay/package/php/8.3/current/bin/php-config. Это важно для корректной сборки и последующей работы расширения, чтобы исключить ошибки компоновки и проблемы несовместимости.

В примерах этой статьи используется PHP 8.3 из дистрибутива ServBay. В реальной работе обязательно заменяйте путь на актуальный для вашей конкретной версии PHP.

Сборка модуля PHP imagick

Модуль imagick — один из самых популярных PHP-расширений для работы с изображениями. Он основан на библиотеке командной строки ImageMagick и поддерживает огромное количество функций: масштабирование, кадрирование, конвертацию форматов, водяные знаки, композитинг и другие операции над изображениями. Вот как собрать и установить модуль imagick для выбранной версии PHP в ServBay:

Шаг 1: Установка зависимостей ImageMagick

Модуль imagick требует предустановленной библиотеки ImageMagick. На macOS рекомендуется использовать менеджер пакетов Homebrew. Если Homebrew еще не установлен — ознакомьтесь с инструкцией на официальном сайте.

Откройте терминал и выполните команду для установки ImageMagick и файлов для разработки:

brew install imagemagick

Шаг 2: Скачивание исходного кода imagick

Теперь нужно получить исходный код модуля с официального сайта PHP расширений (PECL). Перейдите на страницу imagick PECL, выберите нужную (обычно последнюю стабильную) версию и скопируйте ссылку для скачивания. В приведенном примере используется версия 3.7.0:

wget https://pecl.php.net/get/imagick-3.7.0.tgz

Шаг 3: Распаковка и переход в каталог исходников

Распакуйте архив с исходным кодом и войдите в директорию модуля:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Шаг 4: Подготовка среды компиляции (phpize)

Находясь в директории с исходниками, выполните утилиту phpize для вашей версии PHP по полному пути (предполагается, что переменная SERVBAY_PACKAGE_FULL_PATH уже установлена):

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

После успешного выполнения в каталоге появятся скрипт configure и другие необходимые файлы, терминал выведет информацию о подготовке компиляционной среды.

Шаг 5: Конфигурирование сборки

Запустите скрипт configure, чтобы задать дополнительные параметры сборки. Обязательно укажите путь к нужному php-config своей версии PHP, используя параметр --with-php-config:

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

Скрипт автоматически проверит наличие библиотек и заголовков ImageMagick, получит параметры сборки из вашего PHP и подготовит файл Makefile. Если появятся ошибки — скорее всего не хватает какой-либо зависимости или указан неверный путь.

Шаг 6: Сборка и установка модуля

Когда конфигурация завершена и Makefile создан, можно собирать модуль командой make, а затем устанавливать его:

make -j ${CPU_NUMBER}
make install

Параметр ${CPU_NUMBER} (устанавливается скриптом ServBay) позволяет использовать все ядра CPU для ускорения компиляции.

После выполнения make install файл модуля imagick.so будет автоматически скопирован в стандартную директорию расширений выбранной версии PHP в ServBay (например, /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, точный путь зависит от версии PHP и опций сборки).

Шаг 7: Включение модуля

После установки модуля необходимо активировать его в конфигурационном файле нужной версии PHP. В ServBay это удобно делается через графический интерфейс:

• Откройте приложение ServBay
• В меню слева выберите Языки – PHP – PHP 8.3
• На правой панели перейдите на вкладку PHP, прокрутите вниз до секции «Дополнительные параметры», впишите extension=imagick.so
• Нажмите Сохранить, процесс PHP будет автоматически перезапущен с новым расширением

Шаг 8: Проверка загрузки модуля

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

Проверьте статус модуля в командной строке:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

Такой вызов PHP (по нужному пути) с параметром -m выведет все активные модули. Если imagick загружен успешно, вы увидите его в числе расширений.

Для подробной диагностики создайте файл PHP (например, info.php) в корне вашего веб-сайта (по умолчанию — /Applications/ServBay/www) со следующим содержимым: <?php phpinfo(); ?>. Затем откройте через браузер http://localhost/info.php или используемый домен. В выводе страницы найдите раздел "imagick" — вы обнаружите подробную информацию о версии и настройках расширения.

Сборка модулей PHP sqlsrv/pdo_sqlsrv

Расширения sqlsrv и pdo_sqlsrv — это официальные модули PHP для подключения и работы с базами Microsoft SQL Server через ODBC-драйвер. Если вам необходимо работать с SQL Server из PHP в среде ServBay — потребуется их скомпилировать и подключить.

Важно: обязательные зависимости

Для сборки и установки sqlsrv на macOS сначала необходимо установить ODBC-драйвер Microsoft (msodbcsql18) и сопутствующие инструменты (mssql-tools18). Эти пакеты не входят в поставку ServBay, их нужно установить вручную.

Рекомендуется использовать Homebrew. Инструкцию по установке Homebrew смотрите на официальном сайте.

Вот команды для установки драйвера и инструментов Microsoft через Homebrew. Может потребоваться согласие с лицензионным соглашением (экспортируйте переменную HOMEBREW_ACCEPT_EULA=Y):

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Убедитесь, что все зависимости успешно установлены до начала компиляции модуля sqlsrv. Обычно Homebrew размещает библиотеки в /opt/homebrew/ (на Apple Silicon Mac) или /usr/local/ (на Intel Mac). Укажите соответствующие пути в сборке.

Совет

sqlsrv и pdo_sqlsrv — отдельные расширения и собираются по одному, но процедура для обоих идентична. Ниже все шаги приведены для sqlsrv.

Шаг 1: Установка ODBC-драйвера и инструментов Microsoft

(Как указано выше, это обязательный предварительный шаг — убедитесь, что установлены msodbcsql18 и mssql-tools18.)

Шаг 2: Скачивание исходного кода sqlsrv

Скачайте исходные коды расширений с официального сайта PECL. Страница sqlsrv на PECL – выберите нужную версию (приведен пример для версии 5.12.0):

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Шаг 3: Распаковка архивов и переход в каталог исходников

Распакуйте архив и перейдите в рабочий каталог:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Для pdo_sqlsrv все аналогично, здесь пример для sqlsrv

Шаг 4: Подготовка среды компиляции (phpize)

Выполните phpize для вашей версии PHP:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Шаг 5: Конфигурирование сборки (указание путей к зависимостям)

Перед запуском ./configure необходимо явно задать переменные окружения LDFLAGS и CPPFLAGS, чтобы скрипт нашел библиотеки и заголовки, установленные Homebrew, включая ODBC-драйвер Microsoft и unixODBC. Обязательно укажите в команде нужный путь для вашей архитектуры: /opt/homebrew (Apple Silicon) или /usr/local (Intel).

Пример для /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Для корректного поиска заголовков
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: путь к библиотекам (-L/opt/homebrew/lib)
• CPPFLAGS: пути к заголовкам (-I/opt/homebrew/opt/unixodbc/include и -I/opt/homebrew/include)
• ${CPPFLAGS} и ${LDFLAGS} — возможно, уже установлены ServBay и нужны для других целей

Шаг 6: Сборка и установка модуля

Соберите расширение и установите его:

make -j ${CPU_NUMBER}
make install

make install скопирует скомпилированные файлы sqlsrv.so и (если собирали отдельно) pdo_sqlsrv.so в стандартную папку расширений выбранной версии PHP в ServBay.

Шаг 7: Включение модуля

После установки активируйте модуль через интерфейс ServBay:

• Откройте приложение ServBay
• Слева — меню Языки – PHP – PHP 8.3
• На правой панели вкладка PHP, внизу раздел «Дополнительные параметры» — добавьте extension=sqlsrv.so и extension=pdo_sqlsrv.so
• Нажмите Сохранить, PHP автоматически будет перезапущен

Шаг 8: Проверка загрузки модуля

После активации обязательно перезапустите пакет PHP, чтобы изменения вступили в силу.

Проверьте статус в командной строке:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

Если загрузка прошла успешно, в результатах появятся строки sqlsrv и pdo_sqlsrv. Также вы можете убедиться в работоспособности через функцию phpinfo().

Часто задаваемые вопросы (FAQ)

• Вопрос: При компиляции возникает ошибка "Cannot find autoconf" или похожая ошибка?
  • Ответ: Практически наверняка не выполнена инициализация окружения компиляции ServBay. Пересмотрите раздел “Предварительные требования” и обязательно выполните все шаги из документации Вторичная компиляция с использованием ServBay. Необходимые инструменты (autoconf, automake, libtool и др.) должны быть установлены и доступны через переменные среды. Как правило, достаточно запустить скрипт инициализации и перезапустить терминал.
• Вопрос: Скрипт configure не находит какую-либо библиотеку или заголовок?
  • Ответ: Скорее всего, не установлена требуемая библиотека либо не задан путь к ней.
    • Для imagick — убедитесь, что установлены библиотеки и dev-файлы ImageMagick: brew install imagemagick
    • Для sqlsrv — обязательно проверьте, что установлены драйвер Microsoft ODBC (msodbcsql18) и mssql-tools18 через Homebrew. Перед запуском ./configure тщательно проверьте переменные LDFLAGS и CPPFLAGS — все пути должны быть актуальными (например, /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Проверьте, содержат ли пути компиляционной среды ServBay директории Homebrew (если зависимости были установлены через Homebrew), или добавьте их вручную в PATH.
• Вопрос: Ошибка на этапе make или make install?
  • Ответ: Возможные причины:
    • Недостающие зависимости: изучите текст ошибки — он подскажет, чего именно не хватает. Установите необходимые библиотеки или инструменты.
    • Ошибка конфигурирования: перепроверьте шаги configure, убедитесь, что параметр --with-php-config указывает на корректный путь к PHP вашей версии.
    • Проблемы с правами: если скрипт не может записать в каталог расширений, возможно, потребуется использовать sudo make install (делать это нужно осознанно и осторожно).
    • Проблема с исходным кодом: проверьте, корректен ли архив с модулем.
• Вопрос: Модуль .so установлен и включен в .ini, но его не видно в php -m или на странице phpinfo()?
  • Ответ:
    • Чаще всего забыли перезапустить PHP-пакет ServBay. После изменения .ini обязательно используйте панель управления ServBay или командную утилиту для полного перезапуска выбранной версии PHP. Просто обновить страницу или перезапустить веб-сервер Caddy/Nginx недостаточно!
    • Проверьте корректность синтаксиса файла .ini (директива extension=modulename.so).
    • Удостоверьтесь, что параметр extension_dir в php.ini указывает на нужный путь к директории расширений. Его значение можно получить вызовом php-config --extension-dir.
    • Модуль поврежден или не совместим с данным PHP — попробуйте пересобрать, проверьте совместимость исходников с вашей версией PHP, а также изучите логи ошибок (обычно находятся в папке logs внутри директории ServBay).

Итоги

Следуя описанным в этом руководстве шагам, вы сможете с легкостью собирать и подключать пользовательские модули PHP (например, imagick или sqlsrv) в локальной macOS-среде ServBay. Ключевые моменты:

1. Полная инициализация среды компиляции ServBay — обязательна для любых дальнейших действий.
2. Указание точного пути к вашей версии PHP при работе с phpize и php-config.
3. Установка необходимых внешних зависимостей для модулей PHP, их корректное включение в параметры сборки (LDFLAGS, CPPFLAGS).
4. Корректное подключение модуля через конфигурационные файлы PHP (директива extension=modulename.so).
5. Перезапуск пакета PHP в ServBay для активации новых расширений.

ServBay — это мощная универсальная платформа для веб-разработки, поддерживающая интеграцию с MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust и многими другими технологиями. Преимущества ServBay включают поддержку реальных SSL-сертификатов через ACME, простую настройку CORS, автоматические бэкапы (настроек, сайтов, баз, SSL), сброс паролей root БД, централизованные пользовательские корневые и публичные CA для локального HTTPS и многое другое — всё для построения удобного, надёжного и современного workflow разработчика.

Надеемся, это руководство поможет вам быстро и без ошибок интегрировать необходимые функции в вашу локальную PHP-среду ServBay и повысит вашу продуктивность в веб-разработке. Если возникнут дополнительные вопросы — обратитесь к официальной документации или ресурсам поддержки сообщества ServBay.