Hoe een externe PHP-extensie laden in ServBay

ServBay is een krachtige lokale webontwikkelomgeving die standaard voorzien is van veelgebruikte PHP-extensies. Meestal volstaat het om de gewenste extensies eenvoudig te activeren via Pakketten (Packages) -> Talen (Languages) -> PHP-versie -> Extensies in ServBay.

Toch komt het geregeld voor dat ontwikkelaars een externe of zelf-gecompileerde PHP-extensie willen laden die ServBay standaard niet bevat. In dit artikel leggen we stap voor stap uit hoe je zo’n extensie laadt voor een geselecteerde PHP-versie binnen ServBay, aan de hand van ionCube Loader als voorbeeld. De werkwijze is ook van toepassing op andere Zend-extensies of handmatig gecompileerde .so-extensiebestanden.

Speciale opmerking over Zend-extensies: ionCube Loader is een Zend-extensie, wat betekent dat deze dieper integreert met de Zend Engine van PHP. Het is daarom noodzakelijk de configuratie-instructie zend_extension te gebruiken en niet de standaard extension-instructie. Let goed op het juiste gebruik.

Vereisten

• ServBay is reeds geïnstalleerd en draait op je macOS-systeem.
• Je hebt beheerdersrechten en toegang tot systeembestanden en ServBay-instellingen.
• Je bent vertrouwd met het gebruik van de Terminal-app van macOS.
• Je beschikt over het juiste externe PHP-extensiebestand (meestal .so), dat volledig compatibel is met de PHP-versie, architectuur (Intel of Apple Silicon) en build-opties (zoals NTS/ZTS) die je gebruikt in ServBay.

Let op: architectuur-compatibiliteit is essentieel

ServBay biedt native PHP-pakketten voor zowel Intel (x86_64) als Apple Silicon (ARM64, zoals M1/M2/M3/M4 chips). Bij het laden van een .so-extensiebestand is het cruciaal om ervoor te zorgen dat de architectuur van het bestand overeenkomt met die van het gekoppelde PHP-pakket in ServBay.

Bestanden van verschillende architecturen zijn niet uitwisselbaar. Een onjuiste combinatie voorkomt dat PHP start of leidt tot crashes.

Gebruik het file-commando om de architectuur van uitvoerbare bestanden of .so-bestanden te achterhalen:

1. Bepaal de architectuur van het meegeleverde PHP-pakket in ServBay (vervang 8.3 met je werkelijke PHP-versie):

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

   De output zal vergelijkbaar zijn met:

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

   of

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

2. Bepaal de architectuur van het gedownloade of zelf-gecompileerde .so-bestand (vervang xdebug.so door jouw bestandsnaam):

   file xdebug.so

   De output zal vergelijkbaar zijn met:

   xdebug.so: Mach-O 64-bit bundle arm64 # Staat voor Apple Silicon ARM64-architectuur

   of

   xdebug.so: Mach-O 64-bit bundle x86_64 # Staat voor Intel x86_64-architectuur

   Zorg dat de architectuurinformatie van stap 1 en stap 2 exact overeenkomt.

Stappenplan

Stap 1: Download het externe extensiebestand (ionCube Loader als voorbeeld)

1. Ga naar de officiële downloadpagina van ionCube Loader. Kies het juiste pakket gebaseerd op je macOS-architectuur. Voor macOS ARM64 (Apple Silicon M-serie chips) selecteer je de Darwin ARM64-versie. Je kunt bijvoorbeeld onderstaande link gebruiken (controleer altijd of er een nieuwer bestand beschikbaar is op de website): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Na het downloaden heb je een .tar.gz archiefbestand, bijvoorbeeld ioncube_loaders_dar_arm64.tar.gz.

Stap 2: Bepaal de doel-PHP-versie en ServBay extensie-installatiemap

1. Open de ServBay-applicatie.

2. Klik in het navigatiemenu links op Pakketten (Packages) en vervolgens op Talen (Languages).

3. Zoek in de rechterzijde de PHP-versie waarvoor je de ionCube Loader wilt installeren (bijvoorbeeld PHP 8.3) en noteer deze versie.

4. Zoek het extensie-installatiepad (extension_dir) van deze PHP-versie binnen ServBay. Hier moeten .so-bestanden terechtkomen. De exacte locatie is afhankelijk van de ServBay-installatie, PHP-versie en build-opties.

   De betrouwbaarste manier is via terminal-commando:

   Open de Terminal en voer het volgende commando uit (vervang /Applications/ServBay/package/php/8.3/current/bin/php door het pad naar jouw PHP-versie):

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

   De output toont bijvoorbeeld:

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

   Noteer het exacte pad; dit heb je in de volgende stappen nodig.

Stap 3: Pak het loader-bestand uit en plaats het juiste bestand

1. Open de Terminal-app.

2. Navigeer met cd naar de map waarin je het .tar.gz-bestand hebt gedownload (meestal ~/Downloads):

   cd ~/Downloads

3. Pak het archief uit:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Hiermee wordt een nieuwe map ioncube gemaakt.

4. Ga de ioncube-map binnen:

   cd ioncube

5. Zoek in deze map het .so-bestand dat overeenkomt met jouw PHP-versie, bijvoorbeeld ioncube_loader_dar_8.3.so voor PHP 8.3.

6. Kopieer dit bestand naar de in stap 2 gevonden extensie-directory. Stel dat de map is /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ en je gebruikt PHP 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/

   • Let er op dat je altijd het juiste pad gebruikt zoals gevonden via php -i.
   • Controleer dat je het juiste .so-bestand gebruikt dat overeenkomt met de PHP-versie en architectuur (zie de controle bij de vereisten).

Stap 4: Configureer PHP in ServBay

1. Ga terug naar de ServBay-applicatie.

2. Selecteer in het linkermenu Talen (Languages) en klik rechts op de gewenste PHP-versie (bijvoorbeeld PHP 8.3).

3. In het configuratievenster aan de rechterzijde klik je op het PHP-tabblad.

4. Scroll naar beneden naar het tekstveld Additional Parameters (Aanvullende parameters).

5. Voeg de volgende regel toe om het ionCube Loader-bestand aan te wijzen:

   zend_extension = ioncube_loader_dar_8.3.so

   • Let op: Vervang ioncube_loader_dar_8.3.so indien nodig met de naam van het gekopieerde bestand.
   • Gebruik altijd zend_extension bij Zend-extensies als ionCube Loader.
   • Omdat het bestand al in de -directory staat (extension_dir), is alleen de bestandsnaam voldoende; geen volledig pad nodig.
   • Als er al andere configuraties in het tekstvak staan, voeg dit dan als nieuwe regel toe.

   (De afbeelding is een voorbeeld. Het werkelijke scherm kan verschillen afhankelijk van de versie)

6. Klik rechtsonder op Opslaan (Save) om de instellingen te bewaren.

Stap 5: Herstart de PHP-service

Na op Opslaan (Save) te klikken, detecteert ServBay de wijzigingen automatisch en zal de betreffende PHP-dienst(en) soepel herstarten. Je hoeft doorgaans geen verdere herstart uit te voeren.

Stap 6: Controleer of de extensie juist geladen is

Je kunt op twee veelgebruikte manieren controleren of de ionCube Loader correct geladen werd:

1. Verifiëren via de command line:

   • Open de Terminal.

   • Voer dit commando uit (zorg voor het juiste PHP-pad):

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

     Als de extensie goed geladen is, verschijnt een regel met bijvoorbeeld ionCube Loader.

   • Je kunt ook de versie-output controleren:

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

     Een voorbeeld van geslaagde output:

     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.

     Let op de regel: with the ionCube PHP Loader ....

2. Verifiëren via de phpinfo() functie:

   • Maak in de root van je website (bijv. /Applications/ServBay/www/servbay.demo/ of je eigen sitepad) een nieuw PHP-bestand, bijvoorbeeld info.php.
   • Plaats hierin het volgende:

     <?php
     phpinfo();
     ?>

   • Open het bestand in je browser, bijvoorbeeld op http://servbay.demo/info.php (vervang door je werkelijke lokale domeinnaam).
   • Zoek op de phpinfo()-pagina naar “ionCube” (met Cmd+F of Ctrl+F). Bij succesvolle installatie zie je een apart ionCube Loader-blok met versie- en licentiegegevens.

Lijkt alles correct geladen volgens de bovenstaande controle, dan is de extensie succesvol geactiveerd.

Veelvoorkomende problemen en oplossingen

• PHP start niet of crasht: De meest voorkomende oorzaak is architectuur-ongelijkheid tussen de extensie en het PHP-pakket. Controleer zorgvuldig of de architectuur overeenkomt zoals beschreven bij de vereisten. Incompatibele PHP-versie of build-opties kunnen ook problemen opleveren.
• Onjuiste extension_dir-pad: Controleer of je het .so-bestand daadwerkelijk hebt geplaatst in het juiste extension_dir-pad van de gewenste PHP-versie, zoals gevonden met php -i | grep extension_dir.
• Verkeerde configuratie-instructie: Kijk na of je de juiste regel hebt toegevoegd. Voor Zend-extensies moet het zend_extension = bestand.so zijn; voor normale extensies gebruik je extension = bestand.so. De bestandsnaam moet exact overeenkomen met het bestand in de extension_dir (ook hoofdletters/kleine letters).
• Bestandsrechten: Zorg dat de gebruiker waarmee ServBay draait (meestal je macOS-gebruiker) leesrechten heeft voor het .so-bestand en de map. Normaal zijn hier geen problemen, maar controleer bij twijfel de permissies.
• ServBay niet herstart: Zelfs al herstart ServBay meestal vanzelf, probeer bij aanhoudende problemen de betrokken service(s) handmatig te stoppen en opnieuw te starten, of start de hele app opnieuw.
• ionCube-informatie ontbreekt in phpinfo(): Controleer of je daadwerkelijk de juiste PHP-versie gebruikt onder het juiste domein in ServBay, vooral als je meerdere versies of sites beheert.

Samenvatting

Met bovenstaand stappenplan kun je succesvol ionCube Loader of andere externe .so PHP-extensies laden voor een specifieke PHP-versie in ServBay. De sleutel is: identificeer nauwkeurig de doel-PHP-versie, zoek het juiste extension_dir, plaats het compatibele extensiebestand daar en geef het correct door in Additional Parameters met de juiste instructie (zend_extension of extension). Bij problemen volg je de troubleshooting-sectie, met bijzondere aandacht voor architectuur-compatibiliteit en bestandslocaties.