Kompilacja i instalacja niestandardowych modułów PHP w ServBay (macOS)

ServBay to potężne, lokalne środowisko programistyczne stworzone z myślą o systemie macOS. Integruje szeroki wybór pakietów oprogramowania, aby sprostać potrzebom współczesnych twórców stron WWW. Oferuje m.in. PHP, Node.js, Python, Go, Java, bazy danych (MySQL, PostgreSQL, MongoDB), cache (Redis) oraz serwery WWW (Caddy, Nginx, Apache). W każdym z pakietów można korzystać z wielu wersji, co zapewnia elastyczną konfigurację środowiska pod konkretne projekty.

Chociaż ServBay zawiera wiele popularnych modułów PHP, w pewnych scenariuszach developerskich możesz potrzebować skompilować i doinstalować dodatkowe moduły, aby rozbudować funkcjonalność PHP lub zintegrować specyficzne usługi firm trzecich.

Ten poradnik szczegółowo wyjaśnia, jak kompilować i instalować własne moduły dla wybranej wersji PHP w środowisku ServBay. Na przykładzie popularnych rozszerzeń imagick (obsługa grafiki) oraz sqlsrv (łączność z Microsoft SQL Server), krok po kroku przeprowadzimy Cię przez cały proces, abyś sprawnie rozszerzał środowisko PHP w ServBay według indywidualnych potrzeb.

Wymagania wstępne

Ważna informacja

Zanim rozpoczniesz kompilację jakiegokolwiek modułu PHP, najważniejszym krokiem jest poprawna inicjalizacja środowiska kompilacji zgodnie z instrukcjami oficjalnej dokumentacji ServBay oraz prawidłowe ustawienie zmiennych środowiskowych. To niezbędny fundament do udanej kompilacji pakietów ServBay (również modułów PHP). Pominięcie lub niepoprawne wykonanie tego etapu prawie na pewno skutkuje niepowodzeniem – pojawią się błędy takie jak brak poleceń, bibliotek lub nagłówków.

Skrypt inicjalizujący środowisko kompilacji ServBay ustawia kluczowe zmienne, np. PATH (ścieżka do narzędzi kompilacyjnych ServBay), SERVBAY_PACKAGE_FULL_PATH (ścieżka do katalogu pakietów ServBay) oraz CPU_NUMBER (liczba rdzeni używanych przy kompilacji równoległej). Są one niezbędne dla prawidłowego przebiegu kolejnych kroków kompilacji.

Szczegółowe instrukcje inicjalizacji środowiska kompilacji znajdziesz w dokumentacji: Kompilacja pakietów w ServBay. Rekomendujemy dokładne zapoznanie się z tym dokumentem i ścisłe wykonanie wszystkich wskazanych kroków.

Przed przejściem dalej upewnij się, że środowisko kompilacji ServBay zostało zainicjalizowane zgodnie z instrukcją, a wymagane zmienne środowiskowe są ustawione w bieżącej sesji terminalowej.

Znaczenie wskazania wersji PHP

Jedną z kluczowych zalet ServBay jest możliwość instalacji i uruchamiania wielu wersji PHP równolegle na jednym systemie. Taka elastyczność pozwala łatwo dopasować środowisko pod rozmaite projekty. Jednak podczas kompilacji modułu PHP musisz ściśle określić, dla której wersji PHP chcesz go przygotować. Narzędzia takie jak phpize oraz php-config odnoszą się zawsze do konkretnej wersji PHP.

• phpize: Skrypt przygotowujący środowisko budowania rozszerzenia PHP. Odczytuje plik config.m4 i generuje skrypt configure – to standardowy pierwszy krok kompilacji oprogramowania C/C++.
• php-config: Udostępnia szczegółową konfigurację danej wersji PHP, w tym flagi kompilatora, ścieżki do bibliotek, katalog rozszerzeń itp. Skrypt configure odwołuje się do php-config przy generowaniu Makefile, aby zapewnić zgodność rozszerzenia z wybraną wersją PHP.

Dlatego używając phpize, php-config i pokrewnych narzędzi zawsze podawaj ich pełną ścieżkę dla wersji PHP, z którą chcesz skompilować moduł. Dla przykładu, kompilując rozszerzenie dla PHP 8.3 zainstalowanego w ServBay, korzystaj z /Applications/ServBay/package/php/8.3/current/bin/phpize oraz /Applications/ServBay/package/php/8.3/current/bin/php-config. Precyzyjne wskazanie wersji gwarantuje kompatybilność rozszerzenia i zapobiega błędom kompilacji oraz uruchamiania (np. „brak symbolu”).

W poniższym poradniku zakładamy korzystanie z PHP 8.3 w ServBay. Przy własnych operacjach zastąp tę ścieżkę własną, zgodną z potrzebami.

Kompilacja modułu PHP imagick

Moduł imagick cieszy się olbrzymią popularnością – stanowi potężny dodatek do PHP, oparty na bibliotece ImageMagick. Pozwala realizować zaawansowaną obróbkę grafiki: zmiany rozmiaru, kadrowanie, konwersję formatów, nakładanie znaków wodnych, składanie obrazów i inne operacje. Oto systematyczny opis, jak w ServBay wykonać kompilację i instalację tego modułu dla wskazanej wersji PHP:

Krok 1: Instalacja bibliotek ImageMagick

Rozszerzenie PHP imagick wymaga obecności biblioteki ImageMagick w systemie. Na macOS rekomendowanym rozwiązaniem jest menedżer pakietów Homebrew. Jeśli nie masz zainstalowanego Homebrew, zajrzyj na oficjalną stronę Homebrew.

Aby zainstalować ImageMagick i niezbędne biblioteki deweloperskie, w terminalu wpisz:

brew install imagemagick

Krok 2: Pobranie źródła modułu imagick

Kolejny krok to pobranie źródeł modułu imagick z oficjalnej platformy PECL. Wejdź na PECL imagick, sprawdź dostępne wersje (zwykle wybierz najnowszą stabilną) i skopiuj link do pobrania. Przykład poniżej pobiera wersję 3.7.0:

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

Krok 3: Rozpakowanie paczki i wejście do katalogu

Po zakończeniu pobierania, rozpakuj źródła za pomocą tar, następnie przejdź do katalogu modułu:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Krok 4: Przygotowanie środowiska kompilacji (phpize)

W katalogu źródeł uruchom dedykowany dla danej wersji PHP skrypt phpize. Zwróć uwagę, by wskazać pełną ścieżkę dla wersji docelowej. Dla PHP 8.3 i poprawnie ustawionego SERVBAY_PACKAGE_FULL_PATH:

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

Po poprawnym wywołaniu phpize, utworzone zostaną pliki configure oraz inne wymagane do kompilacji. Na konsoli pojawią się komunikaty potwierdzające gotowość środowiska.

Krok 5: Konfiguracja opcji kompilacji

Uruchom wygenerowany właśnie skrypt configure, wskazując za pomocą --with-php-config odpowiedni plik konfiguracyjny PHP:

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

configure sprawdzi obecność niezbędnych bibliotek i nagłówków ImageMagick oraz ścieżki, tworząc odpowiedni Makefile dla procesu kompilacji. W razie błędów sprawdź, czy wszystkie zależności zostały wcześniej zainstalowane.

Krok 6: Kompilacja i instalacja modułu

Gdy proces konfiguracji zakończy się powodzeniem i powstanie plik Makefile, uruchom kompilację oraz instalację:

make -j ${CPU_NUMBER}
make install

Procedura make install umieści plik imagick.so we właściwym katalogu rozszerzeń PHP w ServBay, np. /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/ (dokładna ścieżka zależy od wersji i ustawień kompilatora).

Krok 7: Aktywacja modułu

Po zainstalowaniu modułu należy go włączyć w konfiguracji PHP. ServBay oferuje intuicyjny interfejs graficzny.

• Uruchom aplikację ServBay
• Wybierz po lewej: Języki - PHP - PHP 8.3
• Po prawej, na zakładce PHP, przewiń do “Dodatkowe parametry” i wpisz extension=imagick.so
• Kliknij Zapisz; ServBay automatycznie zrestartuje proces PHP, uwzględniając nowy moduł

Krok 8: Weryfikacja ładowania modułu

Po aktywacji modułu należy zrestartować pakiet PHP w ServBay, aby zmiany zaczęły obowiązywać. Możesz to zrobić przez panel ServBay, klikając przycisk restart przy odpowiedniej wersji PHP, bądź linię komend ServBay (szczegóły – w dokumentacji).

W celu potwierdzenia, że imagick został prawidłowo załadowany, użyj komendy:

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

Korzystanie ze ścieżki $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php gwarantuje sprawdzanie dokładnie tej wersji, dla której kompilowano moduł. Parametr -m listuje aktywne rozszerzenia PHP. Jeśli wszystko przebiegło prawidłowo, zobaczysz wpis dotyczący imagick.

Dla bardziej szczegółowej weryfikacji możesz utworzyć plik PHP (np. info.php) z kodem <?php phpinfo(); ?> w katalogu root serwera WWW (domyślnie /Applications/ServBay/www). Następnie odwiedź http://localhost/info.php lub swoją domenę konfigurowaną w ServBay. W wynikach phpinfo() wyszukaj "imagick" – uzyskasz potwierdzenie aktywacji modułu, wersję oraz konfigurację.

Kompilacja modułów PHP sqlsrv/pdo_sqlsrv

Moduły sqlsrv oraz pdo_sqlsrv są oficjalnymi rozszerzeniami PHP do obsługi baz danych Microsoft SQL Server, wykorzystują sterownik ODBC dostarczany przez Microsoft. Chcąc połączyć się z SQL Server w środowisku PHP pod ServBay, musisz skompilować i zainstalować ten moduł. Oto szczegółowa instrukcja, jak to zrobić:

Uwaga: kluczowe zależności

Na macOS, przed kompilacją modułu sqlsrv, koniecznie zainstaluj oficjalny sterownik ODBC SQL Server (msodbcsql18) oraz narzędzia konsolowe (mssql-tools18). Te komponenty nie są domyślną częścią ServBay, należy je doinstalować samodzielnie.

Rekomendujemy używanie Homebrew – jeśli go nie posiadasz, odwiedź stronę Homebrew, aby zapoznać się z instalacją.

Aby zainstalować sterowniki Microsoft za pomocą Homebrew, wykorzystaj polecenia poniżej. Może być konieczne zaakceptowanie licencji (przy użyciu zmiennej 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

Upewnij się, że wszystkie zależności są zainstalowane przed próbą kompilacji modułu. Zwykle trafiają do /opt/homebrew/ (Mac z Apple Silicon) lub /usr/local/ (Mac z procesorem Intel). Koniecznie zadbaj o prawidłową ścieżkę podczas kompilacji.

Wskazówka

sqlsrv i pdo_sqlsrv to dwa oddzielne moduły – oba kompiluje się podobnie, więc poniżej przykład tylko dla sqlsrv.

Krok 1: Instalacja sterowników Microsoft ODBC i narzędzi

(Jak opisano wyżej – ten etap jest obowiązkowy. Przed przystąpieniem do kompilacji upewnij się, że korzystając z Homebrew zainstalowano msodbcsql18 oraz mssql-tools18.)

Krok 2: Pobranie źródeł sqlsrv

Pobierz najnowsze lub wymaganą wersję źródeł sqlsrv i pdo_sqlsrv z PECL:

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

Krok 3: Rozpakowanie archiwum i wejście do katalogu

Po pobraniu rozpakuj pliki i przejdź do katalogu ze źródłami:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv analogicznie – poniższe przykłady dla sqlsrv

Krok 4: Przygotowanie środowiska kompilacji (phpize)

W katalogu źródeł uruchom odpowiednią dla wersji PHP komendę phpize:

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

Krok 5: Konfiguracja opcji kompilacji (ze ścieżkami zależności)

Znaczną zależność od sterowników ODBC oraz bibliotek unixODBC należy ująć jeszcze przed wywołaniem ./configure — ustawiając zmienne środowiskowe LDFLAGS (dla bibliotek) oraz CPPFLAGS (dla nagłówków). Dzięki temu skrypt znajdzie wymagane pliki. Obowiązkowo wskaż także --with-php-config na konfigurację odpowiedniej wersji PHP.

W zależności od typu Maca (/usr/local dla Intela, /opt/homebrew dla Apple Silicon) dopasuj komendę. Przykład dla /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # dodaj /opt/homebrew/include dla wszystkich nagłówków
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: definiuje dodatkowe ścieżki do bibliotek linkowanych.
• CPPFLAGS: wskazuje ścieżki do plików nagłówkowych (w tym unixODBC). Uwzględnienie ${CPPFLAGS} i ${LDFLAGS} zachowuje ustawienia środowiska ServBay.

Krok 6: Kompilacja i instalacja modułu

Jeśli powstał poprawnie plik Makefile, rozpocznij kompilację i instalację:

make -j ${CPU_NUMBER}
make install

Po tej operacji pliki sqlsrv.so i pdo_sqlsrv.so (jeśli kompilowałeś oba) zostaną skopiowane do odpowiedniej lokalizacji PHP w ServBay.

Krok 7: Aktywacja modułów

Po instalacji należy aktywować moduły w konfiguracji PHP – analogicznie jak dla imagick, przez interfejs ServBay.

• Uruchom program ServBay
• Z bocznego menu przejdź do: Języki - PHP - PHP 8.3
• W sekcji "Dodatkowe parametry" wpisz: extension=sqlsrv.so oraz extension=pdo_sqlsrv.so
• Kliknij Zapisz, a pakiet PHP uruchomi się ponownie z nowym modułem

Krok 8: Weryfikacja ładowania modułów

Po aktywacji, koniecznie zrestartuj pakiet PHP w ServBay.

Weryfikację obecności aktywnych modułów możesz przeprowadzić za pomocą:

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

Jeśli oba moduły zostały poprawnie załadowane, zobaczysz stosowne wpisy w wyjściu komendy. Potwierdzić ich stan i szczegóły można również przez wynik phpinfo().

Często zadawane pytania (FAQ)

• Q: Pojawia się komunikat "Cannot find autoconf" lub podobny podczas kompilacji?
  • O: To niemal zawsze oznaka niepoprawnej inicjalizacji środowiska kompilacji ServBay. Wróć do sekcji „Wymagania wstępne” na początku dokumentu i skrupulatnie wykonaj instrukcje z poradnika Kompilacja pakietów w ServBay. Upewnij się, że narzędzia jak autoconf, automake, libtool są zainstalowane i dodane do zmiennych środowiskowych. Zazwyczaj wystarczy uruchomić skrypt inicjalizacyjny ServBay i zamknąć/otworzyć nowe okno terminala.
• Q: Skrypt configure zgłasza błąd związany z brakiem biblioteki lub nagłówka?
  • O: Oznacza to, że wymagana przez moduł biblioteka systemowa lub nagłówek nie została zainstalowana, albo nie można jej znaleźć.
    • Dla imagick: sprawdź instalację bibliotek deweloperskich ImageMagick (brew install imagemagick).
    • Dla sqlsrv: sprawdź (**koniecznie**) instalację sterownika Microsoft ODBC (msodbcsql18) i narzędzi (mssql-tools18). Przed wywołaniem ./configure sprawdź zmienne LDFLAGS oraz CPPFLAGS – czy uwzględniają ścieżki z Homebrew (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Upewnij się, że ścieżki z Homebrew są też obecne w środowisku kompilacyjnym ServBay (w razie potrzeby dodaj bin Homebrew do PATH).
• Q: make lub make install kończą się błędem?
  • O: Najczęstsze przyczyny:
    • Brak zależności: Sprawdź dokładne komunikaty błędów – najczęściej wskazują, czego brakuje. Zainstaluj brakującą bibliotekę.
    • Niewłaściwa konfiguracja: Wracając do kroku configure, sprawdź, czy parametry (szczególnie --with-php-config) są poprawnie ustawione (dla właściwej wersji PHP w ServBay).
    • Uprawnienia: Komenda make install kopiuje pliki do katalogu PHP ServBay. Jeśli są problemy z uprawnieniami, możesz spróbować sudo make install (zalecana ostrożność!).
    • Uszkodzone źródła: Zweryfikuj integralność pobranej paczki.
• Q: Plik .so istnieje, wskazana jest ścieżka w .ini, ale php -m lub phpinfo() nie widzi modułu?
  • O:
    • Najczęściej: PHP nie został zrestartowany. Po każdej zmianie .ini uruchom ponownie pakiet PHP z poziomu ServBay. Samo odświeżenie strony lub restart serwera WWW (Nginx/Caddy) to za mało — musi to być restart procesu PHP.
    • Błędy w pliku .ini: Sprawdź, czy wprowadziłeś np. extension=modulename.so bez literówek i błędów składni.
    • Zła ścieżka katalogu rozszerzeń: W pliku php.ini sekcja extension_dir musi wskazywać na właściwy katalog ServBay – możesz to sprawdzić komendą php-config --extension-dir.
    • Niezgodność wersji lub uszkodzenie modułu: Powtórz kompilację, pobierz najnowsze źródła, sprawdź zgodność względem wersji PHP. Jeśli pojawiają się specyficzne błędy ładowania w logach PHP (znajdziesz je w katalogu logs ServBay), przeanalizuj komunikaty.

Podsumowanie

Przestrzegając powyższych kroków, jesteś w stanie samodzielnie skompilować i zainstalować własne rozszerzenia PHP (np. imagick i sqlsrv) w lokalnym środowisku ServBay dla macOS. Najważniejsze aspekty procesu to:

1. Poprawna inicjalizacja środowiska kompilacji ServBay – bez tego kolejne kroki się nie powiodą.
2. Wskazanie i używanie odpowiedniej wersji PHP – zawsze korzystaj z właściwej ścieżki do poleceń phpize i php-config konkretnej wersji PHP z ServBay.
3. Rozwiązanie problemów z zależnościami – doinstaluj wymagane biblioteki systemowe i narzędzia (ImageMagick, Microsoft ODBC itp.) oraz przekaż ich ścieżki podczas kompilacji w zmiennych lub argumentach configure.
4. Poprawna aktywacja modułu – modyfikuj lub twórz plik .ini w katalogu conf.d wybranej wersji PHP z poleceniem extension=modulename.so.
5. Restart procesu PHP w ServBay – dopiero wtedy konfiguracja staje się aktywna.

ServBay to wszechstronne środowisko lokalne działające „out of the box”, wspierające szeroki zakres technologii: MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust i więcej. Dodatkowe narzędzia — takie jak automatyczne pozyskiwanie certyfikatów SSL ACME, prosta konfiguracja CORS, automatyczny backup (ustawienia, witryny, bazy, SSL), resetowanie hasła root do bazy, ServBay User CA oraz Public CA do bezpiecznego developmentu HTTPS — jeszcze bardziej skracają czas i upraszczają pracę programisty.

Mamy nadzieję, że ten poradnik ułatwi rozszerzenie środowiska PHP w ServBay o niezbędne moduły i usprawni codzienny web development. W razie innych pytań — zajrzyj do oficjalnej dokumentacji lub społeczności ServBay.