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

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

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

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

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

Важное замечание

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

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

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

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

Почему важно указывать версию PHP

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

Инструменты phpize и php-config тесно связаны с конкретной версией PHP и используются на этапах подготовки компиляции и получения параметров сборки:

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

Именно поэтому при использовании phpize, php-config и других команд, связанных со сборкой PHP, необходимо обязательно указывать полный путь к инструменту той версии PHP, для которой планируется сборка модуля.

Пример путей

Если, например, необходимо собрать модуль для PHP 8.3, установленного через ServBay:

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

Корректный выбор версии гарантирует совместимость модулей с вашим окружением и предотвращает ошибки компиляции или отсутствие нужных символов при запуске.

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

Компиляция модуля PHP imagick

imagick — популярное расширение для PHP, использующее мощную библиотеку ImageMagick и позволяющее выполнять любые манипуляции с изображениями прямо в скриптах PHP (масштабирование, обрезку, конвертацию, добавление водяных знаков, объединение изображений и многое другое). Рассмотрим, как пошагово собрать и установить imagick в ServBay для определенной версии PHP.

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

Модуль PHP imagick зависит от системной библиотеки ImageMagick.

macOS

Рекомендуется использовать менеджер пакетов Homebrew. Если Homebrew ещё не установлен, подробная инструкция доступна на официальном сайте Homebrew.

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

brew install imagemagick

Windows

На Windows ImageMagick устанавливается вручную — скачайте подходящую версию с официального сайта ImageMagick.

Обязательно выбирайте версию с комплектом разработчика (dev libraries) и добавьте путь установки в переменную среды.

Шаг 2: Получение исходников модуля imagick

Далее нужно скачать исходный код модуля с официального репозитория 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 8.3 с установленной переменной 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. В случае ошибок — обычно проблема либо с зависимостями, либо с путями.

Шаг 6: Компиляция и установка

После успешной настройки сгенерируется Makefile. Запустите компиляцию и установку модуля:

make -j ${CPU_NUMBER}
make install

make install автоматически перенесёт скомпилированный файл расширения в стандартную директорию расширений PHP:

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\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
• Нажмите Сохранить, ServBay автоматически перезагрузит процесс PHP с новым модулем

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

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

Для проверки используйте команду:

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

Использование полного пути гарантирует, что проверяется именно нужная версия PHP. Параметр -m выводит список загруженных расширений. Если модуль активен, в выводе появится строка imagick.

Можно дополнительно убедиться, создав в корне веб-сервера PHP-файл info.php:

<?php phpinfo(); ?>

Корневой каталог по умолчанию:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Откройте http://localhost/info.php в браузере или используйте свой домен ServBay. На странице информации PHP найдите раздел "imagick" — если он есть, модуль успешно загружен; здесь же можно посмотреть его параметры и версию.

Компиляция модулей PHP sqlsrv/pdo_sqlsrv

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

Важно: необходимые зависимости

Перед компиляцией и установкой модуля sqlsrv необходимо предварительно установить драйвер ODBC для Microsoft SQL Server и сопутствующие инструменты. Они не входят в стандартный комплект ServBay и устанавливаются вручную.

macOS

Рекомендуется использовать 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

Библиотеки обычно располагаются в /opt/homebrew/ (Apple Silicon) или /usr/local/ (Intel). Эти пути обязательно нужно учитывать при компиляции.

Windows

Скачайте и установите драйвер ODBC с официального сайта Microsoft:

• Microsoft ODBC Driver for SQL Server
• Выберите и установите подходящую версию
• Убедитесь, что драйвер корректно установлен и определяется системой

Только после этого можно переходить к компиляции модуля sqlsrv.

Совет

sqlsrv и pdo_sqlsrv — это два независимых модуля, компилируются по одной схеме; приведённые ниже шаги разбираются на примере sqlsrv.

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

(Как описано выше — выполните установку Homebrew-пакетов msodbcsql18 и mssql-tools18).

Шаг 2: Получение исходников 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. Так как sqlsrv зависит от Homebrew-библиотек Microsoft ODBC и unixODBC, обязательно добавьте пути к lib и include через переменные LDFLAGS и CPPFLAGS перед запуском configure. Не забудьте также указать путь к php-config.

Для Apple Silicon путь к Homebrew — /opt/homebrew (для Intel — /usr/local); в примере используется первый вариант:

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

• LDFLAGS: путь поиска библиотек при сборке.
• CPPFLAGS: путь поиска заголовочных файлов (в т.ч. unixODBC).
• ${CPPFLAGS} и ${LDFLAGS} — дополнительные параметры ServBay.

Шаг 6: Компиляция и установка модуля

После успешной конфигурации — компиляция и установка:

make -j ${CPU_NUMBER}
make install

Модули sqlsrv.so и pdo_sqlsrv.so, если вы собрались их оба, будут автоматически размещены в стандартной директории расширений PHP.

Шаг 7: Активация модуля

Включить модуль можно через графический интерфейс ServBay:

• Откройте ServBay
• В меню слева: Языки > PHP > PHP 8.3
• На вкладке PHP внизу добавьте строки: extension=sqlsrv.so и extension=pdo_sqlsrv.so
• Нажмите Сохранить — PHP автоматически перезапустится и загрузит новые модули

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

После включения обязательно перезапустите пакет PHP в ServBay.

Для проверки используйте команды:

${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

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

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

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

Итоги

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

1. Правильная и полная инициализация компиляторской среды ServBay — база всех дальнейших работ.
2. Точный выбор версии PHP — при работе с phpize и php-config всегда используйте полный путь к той версии, для которой компилируется расширение.
3. Забота о внешних зависимостях — заранее устанавливайте необходимые системные библиотеки (ImageMagick, драйвер Microsoft ODBC и т.д.), настраивайте переменные окружения для их поиска.
4. Корректное подключение модуля — добавляйте строки подключения расширения в конфигурационный файл нужной версии PHP.
5. Перезапуск пакета PHP в ServBay — чтобы конфигурация вступила в силу.

ServBay даёт большой простор для гибкой настройки окружения: помимо ручной сборки PHP-модулей доступны MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust и другие технологии. Среди дополнительных возможностей — автоматическое получение SSL сертификатов через ACME, настройки CORS, регулярное резервное копирование (настройки, сайты, базы, SSL), сброс пароля root у базы данных, собственный User CA и Public CA для локального HTTPS и др.

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