Jak załadować zewnętrzne rozszerzenie PHP w ServBay

ServBay to potężne lokalne środowisko do rozwoju stron WWW, które posiada wbudowane liczne popularne rozszerzenia PHP. Użytkownik zazwyczaj może je skonfigurować i aktywować za pośrednictwem Pakiety (Packages) -> Języki (Languages) -> Wersja PHP -> Rozszerzenia w panelu ServBay.

Czasami jednak deweloperzy potrzebują załadować w ServBay zewnętrzne, nieobejmowane domyślnie przez aplikację, lub samodzielnie skompilowane rozszerzenia PHP. W tym artykule krok po kroku pokazujemy, jak załadować takie rozszerzenie dla wskazanej wersji PHP w ServBay, na przykładzie ionCube Loader. Analogiczny proces dotyczy także innych rozszerzeń Zend oraz własnoręcznie skompilowanych plików .so.

Szczególna uwaga dotycząca rozszerzeń Zend: ionCube Loader jest rozszerzeniem typu Zend, które głębiej integruje się z silnikiem Zend w PHP. Podczas konfiguracji należy więc używać instrukcji zend_extension, a nie standardowego extension używanego dla zwykłych rozszerzeń. Starannie rozróżniaj i stosuj właściwą opcję.

Wymagania wstępne

• ServBay jest zainstalowany i uruchomiony na Twoim macOS.
• Masz uprawnienia administratora do zarządzania plikami systemowymi i konfiguracją ServBay.
• Znasz podstawy korzystania z terminala macOS.
• Dokładnie znasz wersję pliku zewnętrznego rozszerzenia PHP (najczęściej .so), który chcesz załadować, i potwierdziłeś, że jest w pełni kompatybilny z wersją PHP, architekturą (Intel lub Apple Silicon) oraz ustawieniami kompilacji (np. NTS/ZTS) używanymi w ServBay.

Uwaga: Kompatybilność architektury jest absolutnie kluczowa

ServBay udostępnia natywne pakiety PHP zarówno dla architektury Intel (x86_64), jak i Apple Silicon (ARM64, np. procesory M1/M2/M3/M4). Podczas ładowania pliku rozszerzenia .so, upewnij się, że został on skompilowany dla tej samej architektury, co używany w ServBay pakiet PHP.

Nie można mieszać rozszerzeń różnych architektur – niezgodność spowoduje, że PHP nie uruchomi się lub wystąpi awaria.

Architekturę pliku wykonywalnego lub .so sprawdzisz poleceniem file:

1. Sprawdź architekturę pakietu PHP z ServBay (zamień 8.3 na własną używaną wersję PHP):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   Przykładowy wynik:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Oznacza Apple Silicon ARM64

   lub

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Oznacza Intel x86_64

2. Sprawdź architekturę pobranego/skompilowanego pliku rozszerzenia .so (zamień xdebug.so na nazwę swojego pliku):

   file xdebug.so

   Wynik np.:

   xdebug.so: Mach-O 64-bit bundle arm64 # Oznacza Apple Silicon ARM64

   lub

   xdebug.so: Mach-O 64-bit bundle x86_64 # Oznacza Intel x86_64

   Upewnij się, że architektura z kroku 1 i 2 jest identyczna.

Instrukcja krok po kroku

Krok 1: Pobierz plik rozszerzenia (na przykładzie ionCube Loader)

1. Wejdź na oficjalną stronę pobierania ionCube Loader. Wybierz wersję odpowiednią dla architektury Twojego macOS. Dla macOS ARM64 (Apple Silicon M-series) pobierz wersję Darwin ARM64. Możesz użyć bezpośredniego linku (upewnij się, że nie pojawiła się już nowsza wersja – ten jest przykładowy):
   https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Po pobraniu otrzymasz plik archiwum .tar.gz, np. ioncube_loaders_dar_arm64.tar.gz.

Krok 2: Ustal docelową wersję PHP i ścieżkę instalacji rozszerzeń w ServBay

1. Otwórz aplikację ServBay.

2. W lewym menu kliknij Pakiety (Packages) i wybierz Języki (Languages).

3. Na liście wybierz wersję PHP, do której chcesz dodać ionCube Loader (w przykładzie to PHP 8.3). Zanotuj numer tej wersji.

4. Ustal katalog instalacyjny (extension_dir) dla rozszerzeń PHP wybranej wersji w ServBay. To miejsce, gdzie należy umieścić pliki .so. Ścieżka może się różnić w zależności od lokalizacji instalacji, wersji PHP i opcji kompilacji.

   Najpewniejsza metoda to sprawdzenie w terminalu:

   Uruchom Terminal i wykonaj polecenie (podmień ścieżkę na właściwą dla używanego PHP):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   W wyniku zobaczysz fragment: extension_dir => /sciezka/do/katalogu/rozszerzen. Przykładowo:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Zachowaj tę dokładną ścieżkę – przyda się w następnych krokach.

Krok 3: Rozpakuj i umieść plik Loader

1. Otwórz aplikację Terminal.

2. Przejdź do katalogu, gdzie pobrałeś plik .tar.gz (zwykle ~/Downloads):

   cd ~/Downloads

3. Rozpakuj plik:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   W tym katalogu utworzony zostanie nowy folder ioncube.

4. Wejdź do tego folderu:

   cd ioncube

5. Wewnątrz znajdziesz pliki .so dla różnych wersji PHP, np. ioncube_loader_dar_8.3.so. Odnajdź ten odpowiadający Twojej wersji PHP.

6. Skopiuj odpowiedni plik .so do folderu rozszerzeń ustalonego w poprzednim kroku. Dla przykładu, jeśli katalog to /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/, a wersja PHP to 8.3:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Koniecznie zamień w poleceniu ścieżkę docelową na tę otrzymaną za pomocą php -i.
   • Upewnij się, że kopiujesz dokładnie ten plik .so, którego wersja PHP i architektura są w pełni zgodne z pracującym w ServBay PHP (patrz wymagania architektury).

Krok 4: Skonfiguruj PHP w ServBay

1. Wróć do głównego okna programu ServBay.

2. Po lewej wybierz Języki (Languages), następnie na liście po prawej kliknij wybraną wersję PHP (np. PHP 8.3).

3. Rozwiń sekcję konfiguracji po prawej, wybierz zakładkę PHP.

4. Przewiń do pola Additional Parameters (Dodatkowe parametry).

5. Wpisz poniższą linię, wskazując plik Loader:

   zend_extension = ioncube_loader_dar_8.3.so

   • Uwaga: Zamień ioncube_loader_dar_8.3.so na faktyczną nazwę skopiowanego pliku.
   • Stosuj zend_extension, ponieważ ionCube Loader to rozszerzenie Zend (nie używaj extension).
   • Po skopiowaniu pliku do katalogu extension_dir wystarczy sama nazwa pliku (bez całej ścieżki).
   • Jeśli w tym polu są już inne parametry – wpisz tę linijkę w nowym wierszu.

   (Zrzut ekranu jest poglądowy – rzeczywisty wygląd interfejsu może się różnić w zależności od wersji)

6. Kliknij przycisk Save w prawym dolnym rogu, aby zapisać konfigurację.

Krok 5: Zrestartuj usługę PHP

Po kliknięciu Save ServBay automatycznie wykryje zmiany w konfiguracji i postara się płynnie zrestartować odpowiednie usługi (w tym PHP). W większości przypadków nie jest wymagane ręczne ponowne uruchomienie.

Krok 6: Sprawdź, czy rozszerzenie zostało poprawnie załadowane

Istnieją dwa podstawowe sposoby na potwierdzenie, że ionCube Loader jest aktywny:

1. Sprawdzenie z poziomu terminala:

   • Otwórz Terminal.

   • Wykonaj polecenie, by wylistować aktywne moduły PHP (użyj ścieżki do docelowego PHP):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     Jeśli loader jest załadowany, pojawi się linijka zawierająca ionCube Loader.

   • Możesz też sprawdzić wersję PHP oraz dodatkowe informacje:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Przykładowy wynik po sukcesie (numery wersji mogą się różnić):

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Upewnij się, że występuje linijka with the ionCube PHP Loader ....

2. Sprawdzenie przez phpinfo():

   • W głównym katalogu swojej strony (np. /Applications/ServBay/www/servbay.demo/ lub innym własnym) utwórz nowy plik PHP o nazwie info.php.
   • Wklej do niego tylko ten kod:

     <?php
     phpinfo();
     ?>

   • Otwórz stronę w przeglądarce (np. http://servbay.demo/info.php, zamień na własny adres lokalny).
   • W wyświetlonym panelu phpinfo() wyszukaj "ionCube" (użyj Cmd + F lub Ctrl + F). Jeśli loader działa, zobaczysz dedykowaną sekcję z informacjami o ionCube Loader, w tym wersję oraz szczegóły licencji.

Jeśli powyższe metody potwierdzą obecność ionCube Loader, rozszerzenie działa prawidłowo.

Najczęstsze problemy i ich rozwiązania

• Nie uruchamia się PHP lub następuje jego awaria: Najczęstszy powód to niezgodność architektury pomiędzy plikiem rozszerzenia i pakietem PHP. Starannie sprawdź zgodność według kroków opisanych we wstępie. Inne możliwe przyczyny to niezgodność wersji PHP lub odmienny tryb kompilacji.
• Błąd ścieżki extension_dir: Upewnij się, że plik .so został umieszczony w rzeczywistym katalogu extension_dir wskazanym w ServBay dla danej wersji PHP. Najlepiej sprawdzaj zawsze poleceniem php -i | grep extension_dir.
• Błąd w konfiguracji: Zweryfikuj linię dodaną w Additional Parameters w ServBay. Rozszerzenia Zend muszą mieć postać zend_extension = nazwa.so. Nazwa pliku musi być identyczna z tą, którą wgrałeś do katalogu extension_dir (uwzględnij wielkość liter!).
• Problem z uprawnieniami do pliku: Sprawdź, czy użytkownik uruchamiający ServBay (zwykle Twój użytkownik macOS) ma prawa odczytu do pliku .so oraz katalogu, w którym się znajduje. Domyślnie kopiowanie do katalogów ServBay nie powoduje problemów, ale jeśli ręcznie zmieniałeś prawa — sprawdź to.
• Brak restartu ServBay: Zazwyczaj aplikacja restartuje się automatycznie, jednak w razie problemów wykonaj ręcznie restart usług przez interfejs ServBay lub uruchom ponownie całą aplikację.
• Nie widać Loader’a w phpinfo(): Zweryfikuj, czy odwiedzasz właściwą stronę (phpinfo()) obsługiwaną przez odpowiednią wersję PHP oraz czy rozszerzenie jest skonfigurowane właśnie w tej instancji. Jeśli zarządzasz wieloma PHP lub serwisami lokalnymi, upewnij się, że sprawdzasz poprawne środowisko.

Podsumowanie

Jeśli wykonasz powyższe kroki krok po kroku, z łatwością załadujesz ionCube Loader lub dowolne inne (zewnętrzne lub własnoręcznie kompilowane) rozszerzenie PHP w określonej wersji zarządzanej przez ServBay. Kluczowa jest poprawna identyfikacja używanej wersji PHP, odnalezienie katalogu rozszerzeń (extension_dir), umieszczenie w nim poprawnego pliku .so zgodnego z architekturą, a także właściwe wpisanie dyrektywy (zend_extension lub extension) w sekcji Additional Parameters konfiguratora ServBay. W razie problemów skorzystaj ze wskazówek dotyczących rozwiązywania błędów, szczególnie w zakresie zgodności architektury i ścieżek do plików.