Kompilacja i instalacja niestandardowych modułów PHP w ServBay

ServBay to zaawansowane lokalne środowisko deweloperskie dla macOS i Windows, które zawiera szeroki wachlarz pakietów oprogramowania, spełniających potrzeby współczesnych web developerów. Oferuje preinstalowane wersje PHP, Node.js, Python, Go, Java, bazy danych (MySQL, PostgreSQL, MongoDB), systemy cache (Redis) oraz serwery www (Caddy, Nginx, Apache), z obsługą wielu wersji każdego pakietu, co pozwala elastycznie konfigurować środowisko pod konkretne projekty.

Chociaż ServBay posiada wiele popularnych modułów PHP, w określonych przypadkach deweloperskich możesz potrzebować kompilacji i instalacji dodatkowych modułów, by rozszerzyć możliwości PHP lub zintegrować zewnętrzne usługi.

Ten przewodnik szczegółowo opisuje, jak skompilować i zainstalować niestandardowy moduł dla wybranej wersji PHP używanej w ServBay. Przykłady oparte będą na popularnych modułach imagick (przetwarzanie obrazów) i sqlsrv (sterownik bazy danych Microsoft SQL Server), aby pokazać cały proces dodawania nowych funkcji do PHP w ServBay.

Wymagania wstępne

Ważna informacja

Przed kompilacją dowolnego modułu PHP najistotniejszy krok to inicjacja środowiska kompilacyjnego zgodnie z oficjalną dokumentacją ServBay oraz poprawne ustawienie zmiennych środowiskowych systemu. Stanowi to podstawę skutecznej kompilacji pakietów ServBay (w tym modułów PHP). Ominięcie lub nieprawidłowe wykonanie tego kroku najczęściej skutkuje niepowodzeniem kompilacji, błędami typu brak komend, bibliotek lub plików nagłówkowych.

Skrypt inicjujący środowisko kompilacyjne ServBay ustawia kluczowe zmienne jak PATH (do narzędzi budujących ServBay), SERVBAY_PACKAGE_FULL_PATH (do katalogu głównego pakietów ServBay) czy CPU_NUMBER (ilość rdzeni do kompilacji wielowątkowej). Poprawne ustawienie tych wartości jest niezbędne do dalszej kompilacji.

Szczegółowy opis inicjacji środowiska znajdziesz w dokumentacji: Kompilacja pakietu w ServBay. Upewnij się, że rozumiesz i zastosowałeś się do każdego kroku tam opisanych.

Przed kontynuacją kompilacji modułów upewnij się, że środowisko kompilacyjne ServBay jest zainicjowane, a zmienne środowiskowe są prawidłowo ustawione w aktualnej sesji terminala.

Znaczenie wyboru wersji PHP

Jedną z kluczowych cech ServBay jest wsparcie dla wielu wersji PHP na jednym systemie. Pozwala to łatwo przełączać środowiska pod różne projekty. Kompilacja modułu PHP musi być jednak wykonana dla konkretnej wersji PHP. Narzędzia takie jak phpize i php-config są powiązane z odpowiednią wersją PHP.

• phpize – skrypt przygotowujący środowisko kompilacji rozszerzeń PHP; czyta plik config.m4 i generuje skrypt configure – pierwszy krok kompilacji programów w C/C++.
• php-config – dostarcza szczegółowe informacje o zainstalowanej wersji PHP: flagi kompilatora, katalogi nagłówków/bibliotek, ścieżki instalacji rozszerzeń. Skrypt configure odwołuje się do niego, by zapewnić zgodność modułu z wybraną wersją PHP.

Dlatego korzystając z phpize, php-config czy innych komend związanych z budową PHP, należy podać pełną ścieżkę do narzędzi odpowiadających wybranej wersji PHP.

Przykładowe ścieżki

Chcesz skompilować moduł dla PHP 8.3 zainstalowanego w 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

Poprawny wybór wersji gwarantuje kompatybilność modułu oraz brak błędów związanych z nierozpoznanymi symbolami podczas kompilacji i uruchamiania.

W tym przewodniku zakładamy wersję PHP 8.3 w ServBay. Zastąp ścieżki poleceń wersją PHP, dla której kompilujesz moduł.

Kompilacja modułu PHP imagick

imagick to jeden z najczęściej używanych rozszerzeń PHP, oparty na narzędziu ImageMagick. Umożliwia szeroki zakres operacji na obrazach: skalowanie, kadrowanie, konwersje formatów, dodawanie znaków wodnych, kompozycję obrazów i nie tylko. Poniżej znajdują się szczegółowe kroki kompilacji i instalacji imagick dla konkretnej wersji PHP w ServBay:

Krok 1: Instalacja bibliotek ImageMagick

Rozszerzenie imagick wymaga bibliotek ImageMagick zainstalowanych w systemie.

macOS

Zalecane jest użycie menedżera pakietów Homebrew. Jeśli nie masz Homebrew, sprawdź oficjalną stronę Homebrew, gdzie znajdziesz instrukcje instalacji.

Uruchom w terminalu polecenie instalujące ImageMagick i deweloperskie nagłówki:

brew install imagemagick

Windows

Użytkownicy Windows muszą pobrać i zainstalować ImageMagick ręcznie – skorzystaj z oficjalnej strony pobierania ImageMagick.

Podczas instalacji wybierz wariant zawierający biblioteki deweloperskie i dodaj ścieżkę instalacji do zmiennych środowiskowych systemu.

Krok 2: Pobranie źródeł modułu imagick

Pobierz źródła imagick z oficjalnej strony PECL. Odwiedź stronę imagick na PECL, wybierz żądaną wersję (najlepiej najnowszą stabilną) i skopiuj link do pobrania. W przykładzie podano wersję 3.7.0:

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

Krok 3: Rozpakowanie archiwum i wejście do katalogu

Po pobraniu rozpakuj archiwum za pomocą tar i przejdź do katalogu ze źródłami modułu:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Krok 4: Przygotowanie środowiska kompilacji (phpize)

W katalogu źródeł modułu uruchom odpowiednią wersję narzędzia phpize. Przypominamy, by użyć pełnej ścieżki do phpize dla wybranej wersji PHP. Jeśli kompilujesz dla PHP 8.3 i prawidłowo ustawiono zmienną SERVBAY_PACKAGE_FULL_PATH:

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

Jeśli polecenie zakończy się sukcesem, zostanie utworzony skrypt configure oraz pliki potrzebne do kompilacji. W terminalu pojawi się informacja o przygotowaniu środowiska.

Krok 5: Konfiguracja opcji kompilacji

Uruchom wygenerowany skrypt configure, podając za pomocą parametru --with-php-config pełną ścieżkę do właściwego php-config, by skonfigurować kompilację:

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

Skrypt przeanalizuje zależności – w tym biblioteki ImageMagick – i utworzy plik Makefile. Błędy zazwyczaj oznaczają brak lub błędną lokalizację zależności.

Krok 6: Kompilacja i instalacja modułu

Po wygenerowaniu Makefile uruchom kompilację oraz instalację modułu, wykorzystując ${CPU_NUMBER} jako liczbę rdzeni do kompilacji równoległej (wartość ustawiana podczas inicjacji środowiska ServBay):

make -j ${CPU_NUMBER}
make install

Polecenie make install umieszcza plik rozszerzenia w katalogu dla danej wersji 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\

Zwróć uwagę, że ścieżka zależy od wersji PHP i opcji kompilacji.

Krok 7: Włączanie modułu

Po instalacji modułu należy aktywować go w konfiguracji PHP (ServBay pozwala na to w trybie graficznym):

• Uruchom aplikację ServBay
• Po lewej stronie znajdź sekcję Języki – PHP – PHP 8.3
• Wybierz zakładkę PHP, przewiń na dół strony i w sekcji „Dodatkowe parametry” wpisz extension=imagick.so
• Kliknij Zapisz – PHP zostanie automatycznie zrestartowany i wczyta moduł

Krok 8: Weryfikacja ładowania modułu

Po aktywacji modułu zrestartuj pakiet PHP w ServBay, by nowe ustawienia zostały zastosowane. Użyj panelu gui ServBay lub poleceń terminalowych (opisanych w oficjalnej dokumentacji ServBay).

Po restarcie sprawdź, czy imagick został poprawnie załadowany tym poleceniem:

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

Dzięki wywołaniu właściwego binarnego pliku PHP sprawdzasz poprawność dla wybranej wersji. Opcja -m wyświetla aktywne moduły PHP. Jeśli imagick się pojawi, zostało załadowane poprawnie.

Możesz też utworzyć plik np. info.php ze środowisku web root (domyślnie):

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

Z zawartością: <?php phpinfo(); ?>, a potem otworzyć w przeglądarce: http://localhost/info.php (lub własna domena). W wyszukiwaniu na stronie phpinfo() odnajdziesz "imagick" i przeczytasz szczegóły konfiguracji oraz wersję modułu.

Kompilacja modułów PHP sqlsrv/pdo_sqlsrv

Moduły sqlsrv i pdo_sqlsrv to oficjalne rozszerzenia umożliwiające łączność i pracę z bazami danych Microsoft SQL Server. Bazują na sterowniku ODBC dostarczanym przez Microsoft. Jeśli chcesz korzystać z SQL Server w środowisku ServBay z PHP, musisz skompilować i zainstalować te moduły. Poniżej opisane są kroki kompilacji i instalacji:

Uwaga: wymagania wstępne

Przed kompilacją i instalacją modułu sqlsrv należy obowiązkowo zainstalować sterownik Microsoft SQL Server ODBC oraz powiązane narzędzia. Te pakiety nie są domyślnie obecne w ServBay – należy je zainstalować ręcznie.

macOS

Rekomendowane jest użycie Homebrew do instalacji zależności. Jeśli nie masz Homebrew, odwiedź oficjalną stronę Homebrew.

Instalacja sterownika ODBC i narzędzi wygląda następująco. Możesz być poproszony o akceptację licencji (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

Zależności standardowo instalowane są do /opt/homebrew/ (Apple Silicon) lub /usr/local/ (Intel). Przed kompilacją należy je wskazać.

Windows

Pobierz i zainstaluj sterownik ODBC z oficjalnej strony Microsoft:

• Odwiedź Microsoft ODBC Driver for SQL Server
• Pobierz wersję zgodną z Twoim systemem oraz zainstaluj
• Upewnij się, że system wykrywa zainstalowany sterownik

Po instalacji możesz przystąpić do kompilacji sqlsrv.

Wskazówka

sqlsrv i pdo_sqlsrv to dwa osobne moduły, wymagają osobnej kompilacji, ale procedura jest identyczna. Przykład poniżej dotyczy sqlsrv.

Krok 1: Instalacja sterownika Microsoft ODBC i narzędzi

(Patrz wyżej – upewnij się, że sterowniki i narzędzia zostały poprawnie zainstalowane przez Homebrew.)

Krok 2: Pobranie źródeł sqlsrv

Pobierz źródła sqlsrv i pdo_sqlsrv z PECL. Odwiedź stronę sqlsrv na PECL i pobierz najnowsze (lub wybrane) wersje. Przykład używa 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

Krok 3: Rozpakowanie archiwum i wejście do katalogu

Po pobraniu rozpakuj i zmień katalog na źródła modułu:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Analogicznie postępuj dla pdo_sqlsrv – poniżej opis obejmuje sqlsrv

Krok 4: Przygotowanie środowiska kompilacji (phpize)

Przejdź do katalogu źródeł i uruchom odpowiednią wersję phpize dla wybranej wersji PHP i ustawionej zmiennej SERVBAY_PACKAGE_FULL_PATH:

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

Krok 5: Konfiguracja opcji kompilacji (z uwzględnieniem ścieżek zależności)

Wywołaj skrypt configure – przed tym ustaw zmienne środowiskowe LDFLAGS oraz CPPFLAGS, by wskazać na katalogi Homebrew z bibliotekami i nagłówkami (ma to znaczenie ze względu na zależności sqlsrv od unixODBC). Nadal użyj pełnej ścieżki do php-config.

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: ścieżka dla plików bibliotek (np. /opt/homebrew/lib)
• CPPFLAGS: katalogi nagłówków (/opt/homebrew/opt/unixodbc/include, /opt/homebrew/include). ${CPPFLAGS} i ${LDFLAGS} zachowują ustawienia ServBay.

Krok 6: Kompilacja i instalacja modułu

Po wygenerowaniu pliku Makefile, uruchom kompilację oraz instalację modułu:

make -j ${CPU_NUMBER}
make install

Moduł (sqlsrv.so i/lub pdo_sqlsrv.so) zostanie umieszczony w katalogu rozszerzeń dla danego PHP w ServBay.

Krok 7: Włączanie modułu

Po instalacji aktywuj rozszerzenia w panelu konfiguracyjnym ServBay:

• Uruchom aplikację ServBay
• Po lewej: Języki – PHP – PHP 8.3
• Zakładka po prawej: PHP, przewiń na dół, w „Dodatkowe parametry” wpisz: extension=sqlsrv.so oraz extension=pdo_sqlsrv.so
• Zapisz zmiany – PHP zostanie automatycznie zrestartowany i załaduje nowe rozszerzenia

Krok 8: Weryfikacja ładowania modułu

Po aktywacji zrestartuj pakiet PHP, by nowe rozszerzenia zostały załadowane.

W terminalu sprawdź, czy oba moduły są widoczne:

${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 moduły są aktywne, pojawią się w wyniku powyższych poleceń. Dla dokładnej informacji możesz użyć funkcji phpinfo().

Najczęstsze pytania (FAQ)

• P: W trakcie kompilacji pojawia się błąd "Cannot find autoconf" lub podobny?
  • O: To prawie na pewno oznacza, że środowisko kompilacyjne ServBay nie zostało poprawnie zainicjowane. Cofnij się do sekcji „Wymagania wstępne” i wykonaj wszystkie kroki zgodnie z Kompilacja pakietu w ServBay. Upewnij się, że narzędzia takie jak autoconf, automake, libtool są zainstalowane i widoczne w zmiennych środowiskowych. Najczęściej problem rozwiązuje ponowne uruchomienie skryptu inicjującego ServBay i restart terminala.
• P: Skrypt configure nie wykrywa jakiejś biblioteki lub pliku nagłówkowego?
  • O: Oznacza to brak (lub złą lokalizację) zależności systemowej.
    • Dla imagick – upewnij się, że masz zainstalowane nagłówki deweloperskie ImageMagick (Homebrew: brew install imagemagick).
    • Dla sqlsrv – obowiązkowo zainstaluj sterownik Microsoft ODBC (msodbcsql18) oraz mssql-tools18 zgodnie z instrukcją. Przed kompilacją ustaw właściwe zmienne środowiskowe LDFLAGS i CPPFLAGS z katalogami Homebrew (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Sprawdź, czy ścieżka Homebrew jest uwzględniona w ustawieniach ServBay, lub dodaj ręcznie katalogi Homebrew do PATH.
• P: Błąd podczas make lub make install?
  • O: Możliwe przyczyny:
    • Brak zależności: Sprawdź komunikaty – najczęściej zostanie wskazana brakująca biblioteka. Zainstaluj żądaną zależność.
    • Błąd konfiguracji: Sprawdź parametry podane przy configure, szczególnie --with-php-config dla odpowiedniej wersji PHP w ServBay.
    • Uprawnienia: Kopiowanie plików do katalogu instalacyjnego, np. przez make install, może wymagać uprawnień administratora. Jeśli to konieczne, jako ostatnią deskę ratunku – użyj sudo make install (świadomie, ostrożnie).
    • Problem ze źródłami: Upewnij się, że pobrany pakiet źródłowy jest kompletny i nieuszkodzony.
• P: Plik .so znajduje się w katalogu rozszerzeń, został dodany do pliku .ini, ale php -m ani phpinfo() go nie widzi?
  • O:
    • Najczęstsza przyczyna: Brak ponownego uruchomienia pakietu PHP w ServBay po modyfikacji konfiguracji. Restartuj PHP poprzez panel ServBay lub polecenie w terminalu. Restart samego serwera www (Caddy, Nginx) czy odświeżenie strony nie wystarczy.
    • Błąd w pliku .ini: sprawdź pisownię i format (extension=modulename.so).
    • Błąd ścieżki do katalogu rozszerzeń: sprawdź, czy php.ini zawiera poprawny extension_dir (najlepiej użyj polecenia php-config --extension-dir).
    • Problem kompatybilności lub uszkodzenia pliku: skompiluj moduł ponownie. Upewnij się, że wersja źródłowa jest kompatybilna i nieuszkodzona. Przeczytaj plik logów PHP (w katalogu logs w ServBay), by znaleźć szczegóły błędów ładowania modułu.

Podsumowanie

Stosując powyższe instrukcje, skompilujesz i zainstalujesz niestandardowe moduły PHP — takie jak imagick czy sqlsrv — w lokalnym środowisku ServBay. Kluczowe są:

1. Poprawna, pełna inicjacja środowiska kompilacji ServBay – bez tego kolejne kroki mogą się nie powieść.
2. Wskazanie właściwej wersji PHP – używaj pełnych ścieżek do binarnych narzędzi dedykowanych wybranej wersji.
3. Instalacja wszystkich zewnętrznych zależności – biblioteki i narzędzia zainstalowane zgodnie z potrzebami modułu (ImageMagick, ODBC itp.) oraz ich ścieżki zadane w konfiguracji i zmiennych środowiskowych.
4. Aktywacja rozszerzenia – utworzenie pliku .ini lub edycja w panelu ServBay, komenda extension=modulename.so.
5. Restart pakietu PHP w ServBay – gwarantuje załadowanie nowego modułu.

ServBay to kompleksowe rozwiązanie do rozwoju webowego, pozwala na użycie różnych technicznych stacków: MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust i więcej. Udostępnia także praktyczne narzędzia: prawdziwe certyfikaty SSL (ACME), łatwą konfigurację CORS, automatyczne backupy (ustawień, stron www, baz danych, certyfikatów SSL), resetowanie hasła root bazy danych, własne CA na potrzeby lokalnych połączeń HTTPS.

Mamy nadzieję, że ten przewodnik pozwoli Ci szybko i skutecznie rozbudować PHP w ServBay oraz usprawni Twoją pracę przy web development. Jeśli napotkasz problemy, sięgnij po dokumentację ServBay lub skorzystaj ze wsparcia społeczności.