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

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

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

Цей посібник докладно пояснює, як компілювати й інсталювати користувацькі модулі для ваших версій PHP у ServBay. Як приклад, розглядається компіляція популярного модуля обробки зображень imagick та драйвера для Microsoft SQL Server sqlsrv, щоб легко додати необхідний функціонал до PHP у ServBay.

Передумови

Важливе зауваження

Перед компіляцією будь-якого PHP-модуля найважливіше — ініціалізувати середовище компіляції та правильно налаштувати системні змінні згідно інструкції з офіційної документації 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.
• php-config: надає докладну інформацію про інсталяцію обраної версії PHP — опції компілятора, шляхи до файлів, тощо. Сценарій configure використовує ці дані, що забезпечує коректну збірку і зв’язування модулів з цільовою версією PHP.

Отже, використовуючи phpize, php-config чи інші пов’язані команди, обов’язково вказуйте повний шлях саме до тієї версії 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. Під час практичної роботи змініть шляхи згідно версії PHP, до якої прив’язуєте модуль у ServBay.

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

imagick — один з найбільш поширених PHP-модулів для роботи з графічними зображеннями, побудований на бібліотеці ImageMagick. Дозволяє виконувати масштабування, обрізку, зміну форматів, додавання водяних знаків, композицію тощо. Нижче наведено детальні кроки для компіляції й встановлення imagick під певну версію PHP через ServBay.

Крок 1: Встановлення залежності ImageMagick

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

Відкрийте термінал і виконайте інсталяцію ImageMagick та бібліотек розробника:

brew install imagemagick

Крок 2: Завантаження вихідних кодів imagick

Далі отримайте архів із вихідним кодом модуля з офіційного сайту PHP-розширень (PECL). Відвідайте сторінку PECL imagick, знайдіть потрібну версію (зазвичай — останню стабільну) — і скопіюйте посилання на архів. Наприклад, версія 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, для якої компілюєте. Для PHP 8.3 при встановленій змінній SERVBAY_PACKAGE_FULL_PATH:

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

Після виконання цієї команди генерація configure пройде успішно — ви побачите відповідний вивід у терміналі.

Крок 5: Конфігурація параметрів компіляції

Запустіть скрипт configure, передавши йому шлях до php-config обраної версії PHP, щоб він отримав весь актуальний набір налаштувань:

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

configure самостійно знайде всі потрібні бібліотеки та файли, створить файл Makefile для подальшої збірки. Якщо виникнуть помилки — скоріш за все, не інсталювано залежностей чи неправильно прописано шляхи.

Крок 6: Компіляція та встановлення модуля

Після успішної конфігурації запустіть власне складання та копіювання модуля до директорії PHP:

make -j ${CPU_NUMBER}
make install

make install перемістить imagick.so у відповідний каталог розширень вашої версії PHP (наприклад, /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 для застосування змін. Це можна зробити з керуючої панелі або за допомогою CLI інструменту ServBay.

Перевірте, чи модуль завантажився:

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

Тут вказується php саме тієї версії, яку ви збирали у ServBay. Ключ -m показує всі підключені модулі. Якщо все вдалося, imagick буде у списку.

Для більш детальної перевірки створіть в корені web-сайту (наприклад, /Applications/ServBay/www) файл info.php із вмістом <?php phpinfo(); ?>. Перейдіть у браузері за адресою http://localhost/info.php або вашим локальним доменом, і у виводі знайдіть “imagick”.

Компіляція модулів PHP sqlsrv/pdo_sqlsrv

Модулі sqlsrv і pdo_sqlsrv — офіційні розширення PHP, призначені для підключення та взаємодії з базою даних Microsoft SQL Server через ODBC-драйвери Microsoft. Якщо потрібно працювати з SQL Server в оточенні ServBay, дотримуйтесь цих інструкцій.

Важлива попередня умова

Для macOS компіляція sqlsrv потребує попередньо встановленого офіційного ODBC-драйвера Microsoft (msodbcsql18) та командного інструменту (mssql-tools18). Вони не входять у дистрибутив ServBay і мають бути встановлені вручну!

Для інсталяції найзручніше використовувати Homebrew. Якщо Homebrew ще не встановлено, перейдіть на офіційний сайт Homebrew.

Команди для інсталяції ODBC-драйверів та утиліт Microsoft (можливо, буде потрібно погодитись з ліцензією через 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 Mac), або /usr/local/ (Intel Mac). У подальших командах ці шляхи потрібні.

Порада

sqlsrv та pdo_sqlsrv — це окремі модулі, їх потрібно компілювати роздільно, але етапи повністю ідентичні. Далі — приклад для sqlsrv.

Крок 1: Встановлення ODBC-драйверів Microsoft

(Докладно розписано вище — переконайтесь, що встановили msodbcsql18 та mssql-tools18 через Homebrew.)

Крок 2: Завантаження вихідних кодів sqlsrv

Отримайте архіви коду для sqlsrv та pdo_sqlsrv з PECL sqlsrv. Наприклад, версія 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 8.3 із змінною SERVBAY_PACKAGE_FULL_PATH:

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

Крок 5: Налаштування параметрів компіляції (з урахуванням шляхів до залежностей)

Оскільки sqlsrv залежить від ODBC-драйверів Microsoft, інстальованих через Homebrew, та бібліотеки unixODBC, необхідно явно вказати шляхи до бібліотек і хедерів — додавши змінні середовища LDFLAGS та CPPFLAGS. Також передайте шлях до php-config своєї версії PHP.

Вкажіть шляхи залежно від платформи: /opt/homebrew (Apple Silicon), /usr/local (Intel Mac). У прикладі — Homebrew в /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: директива для лінкера, де шукати бібліотеки.
• CPPFLAGS: для препроцесора, де розташовані заголовочні файли.

Крок 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)

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

Висновок

Дотримуючись усіх описаних у цьому посібнику етапів, ви зможете успішно зібрати та встановити власні PHP-модулі (наприклад, imagick і sqlsrv) у середовищі розробки ServBay для macOS. Основні моменти:

1. Правильна і повна ініціалізація середовища компіляції ServBay — ключ до подальшого успіху.
2. Чітке вказання потрібної версії PHP — використовуйте повний шлях у командах phpize і php-config саме до вашої цільової інсталяції.
3. Коректна робота із зовнішніми залежностями — все необхідне (ImageMagick, ODBC тощо) має бути інсталювано, а їхні шляхи — вказані через параметри середовища чи аргументи конфігурації.
4. Активація модулів — у конфігураційних .ini файлах цільового PHP через extension=modulename.so.
5. Завжди перезапускайте PHP у ServBay після застосування змін.

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

Сподіваємось, цей посібник допоможе вам легко додавати будь-які потрібні модулі до PHP під ServBay і підвищити власну ефективність у web-розробці. Для вирішення додаткових питань завжди звертайтесь до офіційної документації ServBay чи спільноти користувачів.