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 plikconfig.m4
i generuje skryptconfigure
– 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ń. Skryptconfigure
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:
bash
brew install imagemagick
1
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
:
bash
wget https://pecl.php.net/get/imagick-3.7.0.tgz
1
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:
bash
tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0
1
2
2
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
:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
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ę:
bash
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config
1
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):
bash
make -j ${CPU_NUMBER}
make install
1
2
2
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” wpiszextension=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:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick
1
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
):
bash
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
1
2
3
2
3
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
:
bash
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
1
2
2
Krok 3: Rozpakowanie archiwum i wejście do katalogu
Po pobraniu rozpakuj i zmień katalog na źródła modułu:
bash
tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0
# Analogicznie postępuj dla pdo_sqlsrv – poniżej opis obejmuje sqlsrv
1
2
3
4
2
3
4
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
:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
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
:
bash
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
1
2
3
2
3
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:
bash
make -j ${CPU_NUMBER}
make install
1
2
2
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
orazextension=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:
bash
${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
1
2
2
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
) orazmssql-tools18
zgodnie z instrukcją. Przed kompilacją ustaw właściwe zmienne środowiskoweLDFLAGS
iCPPFLAGS
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
.
- Dla
- O: Oznacza to brak (lub złą lokalizację) zależności systemowej.
- P: Błąd podczas
make
lubmake 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żyjsudo make install
(świadomie, ostrożnie). - Problem ze źródłami: Upewnij się, że pobrany pakiet źródłowy jest kompletny i nieuszkodzony.
- O: Możliwe przyczyny:
- P: Plik
.so
znajduje się w katalogu rozszerzeń, został dodany do pliku.ini
, alephp -m
aniphpinfo()
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 poprawnyextension_dir
(najlepiej użyj poleceniaphp-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.
- O:
Podsumowanie
Stosując powyższe instrukcje, skompilujesz i zainstalujesz niestandardowe moduły PHP — takie jak imagick
czy sqlsrv
— w lokalnym środowisku ServBay. Kluczowe są:
- Poprawna, pełna inicjacja środowiska kompilacji ServBay – bez tego kolejne kroki mogą się nie powieść.
- Wskazanie właściwej wersji PHP – używaj pełnych ścieżek do binarnych narzędzi dedykowanych wybranej wersji.
- 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.
- Aktywacja rozszerzenia – utworzenie pliku
.ini
lub edycja w panelu ServBay, komendaextension=modulename.so
. - 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.