Aangepaste PHP-modules compileren en installeren in ServBay (macOS)

ServBay is een krachtig lokaal webontwikkelplatform, speciaal ontwikkeld voor macOS. Het integreert een breed scala aan softwarepakketten om te voldoen aan de eisen van de moderne webontwikkelaar. Zo levert ServBay standaard meerdere versies van PHP, Node.js, Python, Go, Java, databases (zoals MySQL, PostgreSQL, MongoDB), caching (Redis) en webservers (Caddy, Nginx, Apache). Voor elk pakket biedt ServBay ondersteuning voor meerdere versies, zodat je jouw ontwikkelomgeving flexibel kunt aanpassen aan de vereisten van elk project.

Hoewel ServBay al veelgebruikte PHP-modules bevat, komt het in specifieke ontwikkelscenario’s voor dat je extra PHP-extensies moet compileren en installeren, bijvoorbeeld om PHP verder uit te breiden of te integreren met een externe dienst.

Deze handleiding biedt een gedetailleerd stappenplan voor het compileren en installeren van aangepaste PHP-modules in je ServBay-omgeving. We nemen de populaire imagick-extensie voor beeldbewerking en de sqlsrv-extensie voor Microsoft SQL Server als voorbeeld. Zo kun je zelf probleemloos extra functionaliteiten aan PHP in ServBay toevoegen.

Voorwaarden

Belangrijk

Voordat je begint met het compileren van PHP-modules, is het van cruciaal belang om de compileeromgeving van ServBay te initialiseren zoals beschreven in de officiële ServBay-documentatie en om de systeemomgevingsvariabelen correct in te stellen. Dit vormt het fundament voor een succesvolle installatie van alle ServBay-pakketten, waaronder PHP-extensies. Sla deze stap dus niet over – als je dit niet goed doet, zullen latere compilaties waarschijnlijk mislukken met foutmeldingen als ‘command not found’, ontbrekende libraries of header-bestanden.

Het initialisatiescript van ServBay zet essentiële variabelen als PATH (voor ServBay's interne buildtools), SERVBAY_PACKAGE_FULL_PATH (het rootpad naar ServBay-pakketten) en CPU_NUMBER (aantal cores voor parallelle compilatie). Deze variabelen zijn vereist voor alle commando’s tijdens het compileerproces.

Zie voor een uitgebreid stappenplan: ServBay-Pakketten Hercompileren. Zorg dat je deze gids volledig begrijpt én uitgevoerd hebt voordat je doorgaat.

Verifieer voor je verdergaat dat de initialisatie van de ServBay-compileeromgeving correct en volledig is verlopen, en dat de genoemde variabelen in je huidige terminalsessie beschikbaar zijn.

Het belang van de juiste PHP-versie kiezen

Een belangrijke kracht van ServBay is het parallel draaien van verschillende PHP-versies op één systeem. Hierdoor kan je moeiteloos schakelen tussen PHP-versies voor elk project. Let er echter op dat, wanneer je PHP-extensies compileert, je altijd voor één specifieke PHP-versie werkt! De voor de build benodigde tools, phpize en php-config, zijn namelijk gekoppeld aan een specifieke PHP-installatie.

• phpize: Bereidt de buildomgeving voor een PHP-extensie voor. Het leest config.m4 en maakt het configureerscript aan – een standaard eerste stap bij het compileren van C/C++-software.
• php-config: Geeft uitgebreide configuratie-informatie van een specifieke PHP-versie, waaronder compilerflags, include/directories en locatie van extensies. Het configureerscript gebruikt php-config om afhankelijkheden te vinden en te zorgen dat de module goed wordt gebonden en geplaatst.

Je moet phpize en php-config dus altijd oproepen via het volledige pad naar de beoogde PHP-versie. Bijvoorbeeld, voor PHP 8.3 in ServBay, gebruik je /Applications/ServBay/package/php/8.3/current/bin/phpize en /Applications/ServBay/package/php/8.3/current/bin/php-config. Alleen zo weet je zeker dat je extensie compatibel is met de bedoelde PHP-omgeving — dat voorkomt build-fouten en runtimeproblemen zoals “symbol not found”.

Alle voorbeelden in deze gids gebruiken PHP 8.3 zoals geleverd door ServBay. Vervang padnamen indien je voor een andere, door ServBay geïnstalleerde PHP-versie werkt.

imagick-module voor PHP compileren

De PHP-extensie imagick is een populaire uitbreiding die de krachtige ImageMagick-bibliotheek via PHP beschikbaar maakt. Met imagick kun je uitgebreide beeldbewerkingen uitvoeren, zoals schalen, bijsnijden, conversie, watermerken en compositing. Hieronder staan de stappen voor het compileren en installeren van imagick voor een specifieke PHP-versie in ServBay:

Stap 1: Installeer de ImageMagick-ontwikkelingbibliotheek

De imagick-extensie vereist de aanwezigheid van de ImageMagick-bibliotheek op je systeem. Op macOS installeer je deze het gemakkelijkst via de Homebrew package manager. Heb je Homebrew nog niet, volg dan de instructies op de officiële Homebrew-website.

Open je terminal en installeer ImageMagick (inclusief headers) met:

brew install imagemagick

Stap 2: Download de imagick-broncode

Download het bronpakket van de imagick-extensie via de officiële PECL-site. Zie PECL imagick voor beschikbare versies (meestal kies je de meest recente stabiele versie). In dit voorbeeld nemen we versie 3.7.0:

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

Stap 3: Pak het bronpakket uit en ga naar de map

Pak het archief uit en navigeer naar de uitgepakte map:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Stap 4: Buildomgeving voorbereiden met phpize

Voer binnen de bronmap het bijbehorende phpize-commando uit van je target PHP-versie (let op: altijd het volledige pad gebruiken!). Als je bijvoorbeeld voor PHP 8.3 compileert en de omgeving is klaar:

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

phpize verwerkt het config.m4-bestand en maakt het configureerscript aan. De output bevestigt dat de buildomgeving juist is ingesteld.

Stap 5: Configuratie van build-opties

Start het configureerscript en wijs met --with-php-config naar het juiste php-config-pad van de doelversie:

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

Het configureerscript zoekt automatisch naar ImageMagick-libraries en headers en genereert een Makefile voor de build. Krijg je fouten, controleer dan of alle afhankelijkheden aanwezig en vindbaar zijn.

Stap 6: Module compileren en installeren

Na een succesvolle configuratie compileer je met make en installeer je de module. De ${CPU_NUMBER}-variabele bepaalt het aantal parallelle buildprocessen voor extra snelheid.

make -j ${CPU_NUMBER}
make install

De module imagick.so wordt nu automatisch geplaatst in het standaard extensiepad van de betreffende PHP-versie bijvoorbeeld /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, afhankelijk van versie en build-opties.

Stap 7: Module activeren

Na installatie schakel je de module in. Via de grafische interface van ServBay doe je dat als volgt:

• Open de ServBay-applicatie
• Navigeer links naar Talen – PHP – PHP 8.3
• In het rechtervenster, kies het tabblad PHP, scroll naar beneden naar “Extra parameters” en voeg extension=imagick.so toe
• Klik op Opslaan — de PHP-service wordt automatisch herstart en de nieuwe module wordt actief

Stap 8: Controleren of de module geladen is

Zorg dat de PHP-package in ServBay wordt herstart zodat de module-instellingen actief zijn. Dit kan via de ServBay-interface (zoek het juiste PHP-pakket en klik herstart), of via de ServBay CLI (zie de ServBay-documentatie voor de juiste commando’s).

Na de herstart kun je in de terminal controleren of imagick geladen is:

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

Door $SERVBAY_PACKAGE_FULL_PATH/php/8.3/current/bin/php aan te roepen, ben je er zeker van dat je de juiste PHP-versie aanspreekt. Met -m zie je alle ingeladen modules. Verschijnt imagick in de output, dan is de extensie actief.

Voor een visuele en uitvoerige controle plaats je een bestand zoals info.php met de code <?php phpinfo(); ?> in de root van je webdirectory (standaard /Applications/ServBay/www). Bezoek http://localhost/info.php of je ingestelde domeinnaam. Zoek op “imagick” in de uitkomst — je ziet dan status, opties en versie.

De PHP sqlsrv/pdo_sqlsrv-extensies compileren

De modules sqlsrv en pdo_sqlsrv zijn officiële extensies van Microsoft om via PHP met Microsoft SQL Server te verbinden. Ze maken gebruik van Microsoft’s ODBC-driver. Wil je vanuit PHP op ServBay toegang tot SQL Server, dan moeten deze modules worden geïnstalleerd. Hieronder lees je de stappen:

Opgelet: belangrijke afhankelijkheden

Om sqlsrv te kunnen compileren onder macOS moet je eerst de Microsoft SQL Server ODBC-driver (msodbcsql18) en het bijbehorende commandlinepakket (mssql-tools18) installeren. Deze zijn niet standaard in ServBay en moeten handmatig toegevoegd worden.

Gebruik Homebrew voor eenvoudige installatie. Nog geen Homebrew? Raadpleeg dan de Homebrew-website.

Installeer de Microsoft ODBC-driver en tools met:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Let op: Tijdens installatie kun je akkoord geven met de licentie via het instellen van HOMEBREW_ACCEPT_EULA=Y. Gewoonlijk worden de pakketten geïnstalleerd in /opt/homebrew/ (Apple Silicon Macs) of /usr/local/ (Intel Macs). Bewaar deze paden voor later.

Tip

sqlsrv en pdo_sqlsrv zijn aparte extensies. De installatiestappen zijn vrijwel identiek; hieronder volgt het voorbeeld voor sqlsrv.

Stap 1: Installeer Microsoft ODBC-driver en tools

(Zoals hierboven genoemd, doorloop eerst deze stap met Homebrew.)

Stap 2: Download de sqlsrv-broncode

Download beide extensies via PECL. Ga naar PECL sqlsrv voor downloadlinks. We gebruiken versie 5.12.0 als voorbeeld:

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

Stap 3: Pak het pakket uit en ga naar de map

Pak het pakket uit en ga naar de bronmap:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Voor pdo_sqlsrv volg je dezelfde stappen

Stap 4: Buildomgeving voorbereiden met phpize

Start in de map het phpize-commando van de bedoelde PHP-versie:

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

Stap 5: Configureer build-opties inclusief afhangende paden

Voer het configureerscript uit en geef de juiste paden voor Homebrew’s ODBC-drivers en de unixODBC-headers. Vooral bij gebruik van Homebrew zijn deze paden cruciaal. Stel omgevingsvariabelen LDFLAGS en CPPFLAGS in vóór je configure draait. Pas de paden aan afhankelijk van je Homebrew-installatie (/usr/local bij Intel Macs, /opt/homebrew bij Apple Silicon Macs). Hieronder een voorbeeld voor /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # /opt/homebrew/include garandeert volledigheid
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: bepaal waar de linker libraries zoekt, bv. Homebrew’s libmap.
• CPPFLAGS: bepaal welke include-mappen voor headers worden toegevoegd (met name unixODBC en andere Homebrew-includes). ${CPPFLAGS} en ${LDFLAGS} behouden bestaande variabelen uit de ServBay-omgeving.

Stap 6: Module compileren en installeren

Compileer, na succesvolle configuratie, met:

make -j ${CPU_NUMBER}
make install

Na installatie komen sqlsrv.so en eventueel pdo_sqlsrv.so in de juiste PHP-extensiemap van ServBay terecht.

Stap 7: Module activeren

Activeer de module (net als bij imagick) via de ServBay-interface:

• Open de ServBay-applicatie
• Klik op Talen – PHP – PHP 8.3
• In het PHP-tabblad, scroll naar “Extra parameters”, vul in: extension=sqlsrv.so én extension=pdo_sqlsrv.so
• Klik op Opslaan; de PHP-service wordt automatisch herstart

Stap 8: Check of de modules laden

Herstart PHP in ServBay altijd na deze stap.

Check in de terminal of sqlsrv (en pdo_sqlsrv) geladen zijn:

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

Als de output deze modules vermeldt, zijn ze correct actief. Ook via phpinfo() kun je hun status en details bekijken.

Veelgestelde vragen (FAQ)

• Vraag: "Cannot find autoconf" of soortgelijke fout bij compileren?
  • Antwoord: Dit betekent vrijwel zeker dat de ServBay-compileeromgeving niet goed is geïnitialiseerd. Ga terug naar het hoofdstuk "Voorwaarden" en controleer of je de instructies uit de ServBay-pakketten hercompileren documentatie hebt gevolgd. Zorg dat tools als autoconf, automake en libtool beschikbaar en via het PATH vindbaar zijn. Meestal is het (opnieuw) uitvoeren van het initialisatiescript en een nieuwe terminal voldoende.
• Vraag: configure faalt en meldt missing libraries of headers?
  • Antwoord: Dit komt doordat een benodigde syslibrary of header ontbreekt of niet wordt gevonden.
    • Voor imagick: Installeer ImageMagick dev-libraries, bijvoorbeeld via brew install imagemagick.
    • Voor sqlsrv: Controleer of je Microsoft ODBC-driver (msodbcsql18) en mssql-tools18 via Homebrew hebt geïnstalleerd. Controleer vóór ./configure of je LDFLAGS en CPPFLAGS goed zijn ingesteld (middels de juiste paden, zoals /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Zorg dat alle paden van Homebrew in de compileeromgeving van ServBay beschikbaar zijn, of voeg Homebrew’s bin-directory toe aan je PATH.
• Vraag: make of make install slaagt niet?
  • Antwoord: Er kunnen diverse oorzaken zijn:
    • Ontbrekende build-afhankelijkheden: Kijk waar de fout optreedt en installeer die ontbrekende library.
    • Verkeerde configuratie: Controleer vooral het pad dat je bij --with-php-config aangeeft – het moet naar de goede PHP-versie van ServBay wijzen.
    • Permissieproblemen: Moet je wellicht make install met sudo draaien? (Let op: alleen indien nodig en doe dit bewust.)
    • Broncodeprobleem: Check of de source-archive volledig en niet corrupt is.
• Vraag: .so-bestand staat in de extensiemap, .ini is toegevoegd, maar nog steeds niet zichtbaar via php -m of phpinfo()?
  • Antwoord:
    • Meest voorkomend: De PHP-service van ServBay is niet herstart. Nadat de .ini aangepast is, moet je altijd het betreffende PHP-pakket herstarten via ServBay. Alleen de webserver herstarten (Caddy/Nginx/Apache) is niet voldoende.
    • .ini-syntaxfout: Controleer op typefouten, formaat en gebruikte bestandsnaam (extension=modulenaam.so).
    • Foute extensie-directory: Kijk in php.ini of extension_dir juist ingesteld is. make install plaatst de module zoals aangegeven door php-config --extension-dir.
    • Beschadigd/ongeschikt bestand: Compileer opnieuw, check versiecompatibiliteit en herinner je dat andere PHP-versies een andere extensie-map kunnen hebben. Controleer ook de PHP-logbestanden (bijvoorbeeld in de logs-map van ServBay) voor foutmeldingen bij het laden van modules.

Samenvatting

Met de stappen uit deze handleiding kun je aangepaste PHP-modules als imagick en sqlsrv succesvol compileren en installeren in de ServBay macOS ontwikkelomgeving. De belangrijkste factoren zijn:

1. Een correcte en complete initialisatie van de ServBay-compileeromgeving – de onmisbare basis voor alle compilatie-acties.
2. Gebruik van de juiste PHP-versie en paden – wees nauwkeurig bij het kiezen van je doelversie voor phpize en php-config.
3. Het oplossen van externe module-afhankelijkheden – installeer (system)libraries en tools volgens de specificaties van elke module, en geef ze correct door bij ./configure met bijvoorbeeld LDFLAGS en CPPFLAGS.
4. Correct inschakelen van de module – maak of wijzig een .ini-bestand in het conf.d-mapje van de doel-PHP-versie en voeg daar bijvoorbeeld extension=modulenaam.so toe.
5. Herstart altijd de PHP-service van ServBay – zodat alle nieuwe instellingen en geladen modules actief worden.

ServBay is een veelzijdig platform dat je maximale flexibiliteit biedt. Naast de besproken PHP-modules ondersteunt en integreert ServBay ook MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust en meer. Extra handige functionaliteiten zijn onder andere ACME SSL-aanvraag, eenvoudige CORS-configuratie, automatische backups (instellingen, websites, databases, SSL-certificaten), het resetten van rootwachtwoorden, en het uitgeven van lokale SSL-certificaten (ServBay User CA en Public CA) voor HTTPS-ontwikkeling.

Hopelijk helpt deze handleiding je om snel en efficiënt extra functionaliteit toe te voegen aan PHP binnen ServBay, zodat je webprojecten soepel en professioneel ontwikkeld kunnen worden. Heb je meer vragen, raadpleeg dan vooral de ServBay-documentatie of zoek support in de community.