Benutzerdefinierte PHP-Module in ServBay kompilieren und installieren (macOS)

ServBay ist eine leistungsstarke lokale Web-Entwicklungsumgebung, speziell für macOS entwickelt. Sie bietet eine umfassende Sammlung von Softwarepaketen, die die Anforderungen moderner Webentwickler erfüllen – darunter vorinstallierte Versionen von PHP, Node.js, Python, Go, Java, Datenbanken (wie MySQL, PostgreSQL, MongoDB), Caching-Systeme (Redis) sowie Webserver (Caddy, Nginx, Apache). Für jedes Paket stehen zudem mehrere Versionen zur Auswahl, sodass Sie die Umgebung flexibel anhand Ihrer Projektanforderungen wechseln können.

Obwohl ServBay bereits viele gängige PHP-Module umfasst, besteht in speziellen Entwicklungsszenarien oft die Notwendigkeit, zusätzliche PHP-Module zu kompilieren und zu installieren, um die Funktionalität von PHP zu erweitern oder bestimmte Drittanbieter-Services einzubinden.

In diesem Beitrag erhalten Sie eine detaillierte Schritt-für-Schritt-Anleitung, wie Sie für Ihre PHP-Version in ServBay benutzerdefinierte Module kompilieren und installieren. Anhand der populären Module imagick (Bildverarbeitung) und sqlsrv (Microsoft SQL Server-Treiber) zeigen wir beispielhaft den vollständigen Ablauf, damit Sie die gewünschten Features problemlos in Ihre PHP-Umgebung bei ServBay einbinden können.

Voraussetzungen

Wichtiger Hinweis

Bevor Sie mit dem Kompilieren eines PHP-Moduls beginnen, ist der allerwichtigste Schritt, die Initialisierung der Build-Umgebung gemäß der offiziellen ServBay-Dokumentation abzuschließen und die Systeme-Umgebungsvariablen korrekt zu setzen. Dies ist die Grundlage für eine erfolgreiche Kompilierung von ServBay-Paketen (inklusive PHP-Module). Wird dieser Schritt übersprungen oder nicht korrekt ausgeführt, schlägt die Kompilierung mit hoher Wahrscheinlichkeit fehl – es können Fehler wie fehlende Befehle, Bibliotheken oder Header-Dateien auftreten.

Das Initialisierungsskript der ServBay-Build-Umgebung setzt essentielle Umgebungsvariablen, zum Beispiel PATH (zeigt auf die Buildtools innerhalb von ServBay), SERVBAY_PACKAGE_FULL_PATH (zeigt auf das Stammverzeichnis der ServBay-Pakete) sowie CPU_NUMBER (für paralleles Kompilieren mit mehreren Kernen). Diese Variablen sind für die nachfolgenden Kommandos beim Bauprozess unerlässlich.

Eine detailreiche Anleitung zur Initialisierung der Build-Umgebung finden Sie in der Dokumentation: Pakete mit ServBay erneut kompilieren. Stellen Sie sicher, dass Sie alle Schritte verstanden und exakt wie beschrieben ausgeführt haben.

Bitte überprüfen Sie vor der Kompilierung, ob Sie die oben genannten Schritte zur Initialisierung der ServBay-Build-Umgebung erfolgreich abgeschlossen und die zugehörigen Umgebungsvariablen in Ihrer aktuellen Terminal-Sitzung korrekt gesetzt haben.

Wichtigkeit der PHP-Version-Angabe

Ein zentrales Feature von ServBay ist die Möglichkeit, verschiedene PHP-Versionen parallel zu installieren und zu betreiben. Entwickler können dadurch problemlos für unterschiedliche Projekte zwischen PHP-Umgebungen wechseln. Allerdings muss beim Kompilieren von PHP-Modulen immer gezielt auf die gewünschte PHP-Version Bezug genommen werden, da die Tools phpize und php-config versionsspezifisch sind.

• phpize: Ein Skript, das das Build-Environment für PHP-Erweiterungsmodule vorbereitet. Es liest die Datei config.m4 und generiert daraus ein standardisiertes configure-Skript – ein üblicher erster Schritt bei der Kompilierung von C/C++-Software.
• php-config: Dieses Skript liefert detaillierte Informationen zur jeweiligen PHP-Installation, wie Compiler-Flags, Include-Verzeichnisse, Verzeichnisse für Bibliotheken und Extensions. Das configure-Skript nutzt die Ausgaben von php-config, um den Modulbau passend zur Ziel-PHP-Version zu ermöglichen.

Deshalb gilt: Bei der Verwendung von phpize, php-config oder anderen Build-Befehlen müssen Sie immer den vollständigen Pfad zum gewünschten PHP-Version-Tool angeben. Beispiel: Wenn Sie ein Modul für die in ServBay installierte PHP-Version 8.3 bauen möchten, verwenden Sie /Applications/ServBay/package/php/8.3/current/bin/phpize und /Applications/ServBay/package/php/8.3/current/bin/php-config. Die Wahl der richtigen Version stellt sicher, dass das Modul auch mit Ihrer Zielumgebung kompatibel ist und Sie keine Laufzeitfehler (wie "Symbol not found") erhalten.

Die Beispiele in dieser Anleitung beziehen sich auf PHP 8.3 innerhalb von ServBay. Ersetzen Sie den Pfad in Ihren eigenen Schritten immer durch den exakten Pfad der PHP-Version, für die Sie das Modul bauen wollen.

PHP imagick Modul kompilieren

Das Modul imagick ist eine sehr beliebte PHP-Erweiterung, die auf der leistungsstarken ImageMagick-Bibliothek basiert und eine Vielzahl an Bildbearbeitungsfunktionen ermöglicht. Mit imagick können Sie in PHP komplexe Bildverarbeitungsoperationen wie Skalierung, Zuschnitt, Formatkonvertierung, Wasserzeichen, Bildmontage und mehr vornehmen. Nachfolgend finden Sie die detaillierten Schritte zur Kompilierung und Installation des imagick-Modules für eine bestimmte PHP-Version in ServBay:

Schritt 1: ImageMagick-Abhängigkeiten installieren

Das PHP-Modul imagick benötigt die ImageMagick-Bibliotheken auf Systemebene. Unter macOS empfiehlt sich die Installation per Homebrew. Falls Homebrew noch nicht installiert ist, besuchen Sie die Homebrew-Website für eine Anleitung.

Starten Sie Ihr Terminal und geben Sie folgenden Befehl ein, um ImageMagick und dessen Entwicklerbibliotheken zu installieren:

brew install imagemagick

Schritt 2: Quellcode des imagick-Moduls beziehen

Laden Sie das Quellpaket von imagick von der offiziellen PECL-Webseite herunter. Besuchen Sie die PECL imagick Seite, wählen Sie die benötigte (meistens neueste stabile) Version und kopieren Sie den Download-Link. Im folgenden Beispiel verwenden wir Version 3.7.0:

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

Schritt 3: Quellpaket entpacken und Verzeichnis wechseln

Nach dem Download entpacken Sie das Archiv und wechseln in das entpackte Quellverzeichnis:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Schritt 4: Buildumgebung vorbereiten (mit phpize)

Im Quellverzeichnis angekommen, bereiten Sie die Buildumgebung mit dem phpize-Werkzeug der gewünschten PHP-Version vor. Wie oben beschrieben, ist der vollständige Pfad zu verwenden. Angenommen, Sie erstellen das Modul für PHP 8.3 und haben die Variable SERVBAY_PACKAGE_FULL_PATH richtig gesetzt:

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

Nach erfolgreichem Ausführen von phpize durchsucht das Tool die Datei config.m4 und generiert das benötigte Buildsystem. Es erscheint eine Ausgabe, die signalisiert, dass das Kompilierungs-Environment bereit ist.

Schritt 5: Buildoptionen konfigurieren

Führen Sie das erzeugte configure-Skript aus, um die Kompilierungsoptionen anzugeben. Dabei ist es wichtig, mit --with-php-config den Pfad zur gewünschten PHP-Version explizit anzugeben, damit alle Informationen korrekt übernommen werden.

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

Das Skript sucht Abhängigkeiten wie Bibliotheken und Headerdateien von ImageMagick und erstellt eine Makefile. Bei Fehlern fehlen meist Bibliotheken oder Pfade sind inkorrekt.

Schritt 6: Modul kompilieren und installieren

Erfolgreiches Konfigurieren erzeugt das Makefile. Nun kompilieren Sie das Modul mit make und installieren es mit make install. Die Variable ${CPU_NUMBER} (bei der Initialisierung gesetzt) beschleunigt als Thread-Zahl die parallele Kompilierung.

make -j ${CPU_NUMBER}
make install

Das Kommando make install kopiert das kompilierte imagick.so automatisch in das Extensionsverzeichnis der entsprechenden PHP-Version in ServBay (z.B. /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, abhängig von Version und Build-Optionen).

Schritt 7: Modul aktivieren

Nach dem Installieren muss das Modul in der Konfiguration der Ziel-PHP-Version aktiviert werden. ServBay stellt hierfür eine grafische Oberfläche bereit.

• Starten Sie das ServBay-Programm
• Navigieren Sie im linken Menü zu Sprache – PHP – PHP 8.3
• Wählen Sie rechts den Tab PHP, scrollen Sie nach unten und geben Sie unter "Zusätzliche Parameter" den Eintrag extension=imagick.so ein
• Klicken Sie auf Speichern, wodurch der PHP-Prozess automatisch neu gestartet und das Modul geladen wird

Schritt 8: Modul-Ladung überprüfen

Nach dem Aktivieren müssen Sie das PHP-Paket in ServBay neu starten, damit die Änderungen greifen. Nutzen Sie dazu die grafische Oberfläche von ServBay, wählen Sie die jeweilige PHP-Version aus und klicken Sie auf „Neustarten“ – alternativ steht auch ein Kommandozeilentool von ServBay zur Verfügung (siehe offizielle Dokumentation).

Nach dem PHP-Neustart prüfen Sie die korrekte Ladung des imagick-Moduls im Terminal:

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

So stellen Sie sicher, dass exakt die gewünschte PHP-Version verwendet wird. Der Schalter -m listet alle geladenen PHP-Module auf. Sehen Sie in der Ausgabe imagick, ist das Modul erfolgreich eingebunden.

Eine noch ausführlichere Prüfung können Sie vornehmen, indem Sie im Web-Root-Verzeichnis (standardmäßig /Applications/ServBay/www) eine PHP-Datei (z.B. info.php) mit folgendem Inhalt erstellen: <?php phpinfo(); ?>. Rufen Sie dann im Browser http://localhost/info.php oder Ihren konfigurierten ServBay-Domainnamen auf. Suchen Sie auf der phpinfo()-Seite nach "imagick", um Details zum geladenen Modul und dessen Einstellungen anzuzeigen.

PHP sqlsrv/pdo_sqlsrv-Modul kompilieren

Die Erweiterungen sqlsrv und pdo_sqlsrv sind offizielle PHP-Module für den Zugriff und die Verwaltung von Microsoft SQL Server-Datenbanken. Sie basieren auf dem von Microsoft bereitgestellten ODBC-Treiber. Wenn Sie aus ServBay mit SQL Server arbeiten möchten, benötigen Sie diese Module. Hier die einzelnen Schritte zur Kompilierung und Installation im ServBay-Umfeld:

Hinweis: Zentrale Voraussetzung

Für das Kompilieren und die Installation von sqlsrv-Modulen unter macOS müssen Sie vorab die von Microsoft gelieferten SQL Server ODBC-Treiber (msodbcsql18) sowie die Kommandozeilen-Tools (mssql-tools18) installieren. Diese Software wird nicht mit ServBay geliefert und muss manuell bezogen werden.

Die Installation empfiehlt sich mit Homebrew. Sollte Homebrew noch nicht auf Ihrem System sein, besuchen Sie die offizielle Webseite.

Installieren Sie den Microsoft ODBC-Treiber und die Tools mit folgenden Homebrew-Kommandos. Sie werden eventuell zur Zustimmung der Lizenzbedingungen per Environment-Variable (HOMEBREW_ACCEPT_EULA=Y) aufgefordert.

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

Stellen Sie unbedingt sicher, dass diese Abhängigkeiten vor der Modulkompilierung erfolgreich eingerichtet sind. Sie werden meist in /opt/homebrew/ (Apple Silicon) oder /usr/local/ (Intel Macs) installiert. Beim Kompilieren sind diese Pfade korrekt einzubinden.

Tipp

sqlsrv und pdo_sqlsrv sind eigenständige Module und müssen separat kompiliert werden – die Vorgehensweise ist aber nahezu identisch, nachfolgend wird beispielhaft sqlsrv gezeigt.

Schritt 1: Microsoft ODBC-Treiber und Tools installieren

(Wie oben beschrieben, führen Sie die Homebrew-Installation von msodbcsql18 und mssql-tools18 unbedingt vorher durch.)

Schritt 2: Quellcode von sqlsrv beziehen

Laden Sie die Quellarchive für sqlsrv und pdo_sqlsrv von der offiziellen PECL-Seite herunter. Besuchen Sie die PECL sqlsrv Seite und wählen Sie die gewünschte Version. Im Beispiel nutzen wir die Version 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

Schritt 3: Quellpaket entpacken und Verzeichnis wechseln

Entpacken Sie die heruntergeladene Datei und wechseln Sie in das Verzeichnis:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Für pdo_sqlsrv verfahren Sie genauso – alle weiteren Schritte werden mit sqlsrv exemplarisch erklärt.

Schritt 4: Buildumgebung vorbereiten (mit phpize)

Rufen Sie im Quellverzeichnis das phpize-Tool für die gewünschte PHP-Version auf. Beispiel:

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

Schritt 5: Buildoptionen konfigurieren (mit Pfadangaben für Abhängigkeiten)

Starten Sie configure. Da sqlsrv auf die Libraries des Microsoft ODBC-Treibers und von unixODBC angewiesen ist, müssen vor dem Aufruf von ./configure die Umgebungsvariablen LDFLAGS und CPPFLAGS passend gesetzt werden, damit die nötigen Bibliotheken und Header-Dateien gefunden werden. Geben Sie zudem mit --with-php-config die Ziel-PHP-Version an.

Passen Sie den Pfad je nach Ihrem Homebrew-Installationsort an (/opt/homebrew bei aktuellen Macs, /usr/local bei Intel-Systemen):

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

• LDFLAGS: Gibt an, in welchen Verzeichnissen nach Bibliotheken gesucht werden soll. -L/opt/homebrew/lib zeigt auf den üblichen Library-Pfad von Homebrew.
• CPPFLAGS: Gibt an, in welchen Verzeichnissen Header-Dateien gesucht werden. -I/opt/homebrew/opt/unixodbc/include weist auf die Location des unixODBC-Headers, -I/opt/homebrew/include deckt ggf. benötigte weitere Includes ab. ${CPPFLAGS} und ${LDFLAGS} übernehmen die von ServBay gesetzten Werte.

Schritt 6: Modul kompilieren und installieren

Nach erfolgreichem configure generiert das System ein Makefile. Starten Sie die Kompilierung und nehmen Sie die Installation vor:

make -j ${CPU_NUMBER}
make install

Das Skript make install verschiebt die kompilierte sqlsrv.so sowie ggfs. auch pdo_sqlsrv.so ins Extensions-Verzeichnis der richtigen ServBay-PHP-Version.

Schritt 7: Modul aktivieren

Nach dem Build fügen Sie auch dieses Modul in der Konfig der Ziel-PHP-Version hinzu. Nutzen Sie das grafische Interface von ServBay:

• ServBay-Programm starten
• Menü links: Sprache – PHP – PHP 8.3
• Rechts die Registerkarte PHP auswählen, ganz nach unten scrollen und bei "Zusätzliche Parameter" die beiden Zeilen extension=sqlsrv.so sowie extension=pdo_sqlsrv.so eintragen
• Auf Speichern klicken; der entsprechende PHP-Prozess wird automatisch neugestartet

Schritt 8: Modul-Ladung überprüfen

Nach dem Aktivieren unbedingt das PHP-Paket in ServBay neu starten.

Prüfen Sie die erfolgreiche Einbindung der Module wie folgt im Terminal:

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

Bei erfolgreicher Aktivierung werden die Namen sqlsrv und pdo_sqlsrv in der Ausgabe erscheinen. Auch kann die Einbindung über phpinfo() verifiziert werden.

Häufig gestellte Fragen (FAQ)

• F: Während make-/Kompilierung erscheint "Cannot find autoconf" oder ähnliches?
  • A: Dies ist ein Hinweis, dass die ServBay-Build-Umgebung nicht korrekt initialisiert wurde. Prüfen Sie die „Voraussetzungen“ am Anfang dieser Anleitung und folgen Sie exakt den Anweisungen im Abschnitt Pakete mit ServBay erneut kompilieren. Kontrollieren Sie, dass alle Build-Tools (wie autoconf, automake, libtool) installiert und die Pfade korrekt gesetzt sind. Das Ausführen des Init-Skripts und ein anschließender Terminal-Neustart lösen in der Regel das Problem.
• F: Das configure-Skript bricht ab, weil eine Bibliothek oder Headerdatei nicht gefunden wird?
  • A: Eine erforderliche Systembibliothek oder Headerdatei fehlt oder die Pfadangabe ist fehlerhaft.
    • Für imagick: Installieren Sie die ImageMagick-Entwicklerbibliotheken per Homebrew: brew install imagemagick.
    • Für sqlsrv: Prüfen Sie, ob Microsoft ODBC-Treiber und mssql-tools wie oben beschrieben per Homebrew installiert wurden. Stellen Sie sicher, dass beim Aufruf von ./configure die Umgebungsvariablen LDFLAGS und CPPFLAGS korrekt gesetzt sind (inkl. /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include usw.).
    • Prüfen Sie im ServBay-Build-Umgebungs-Setup, ob alle relevanten Homebrew-Pfade enthalten sind (falls Systempakete via Homebrew installiert wurden) oder ob Sie deren Bin-Ordner zum PATH hinzufügen müssen.
• F: make oder make install schlägt fehl?
  • A: Fehler beim Kompilieren/Installieren können verschiedene Ursachen haben:
    • Fehlende Build-Abhängigkeiten: Überprüfen Sie die Fehlermeldungen und installieren Sie eventuell fehlende Bibliotheken/Binärdateien nach.
    • Fehler bei der Konfiguration: Prüfen Sie die Parameter im configure-Schritt, insbesondere ob --with-php-config auf die gewünschte PHP-Version in ServBay verweist.
    • Berechtigungsprobleme: make install kopiert Dateien in das PHP-Extension-Verzeichnis von ServBay, es können dazu spezielle Rechte notwendig sein. Gegebenenfalls hilft sudo make install (mit Vorsicht zu verwenden!).
    • Probleme mit dem Quellpaket: Kontrollieren Sie, ob das heruntergeladene Archiv fehlerfrei und vollständig ist.
• F: Das Modul-File .so liegt im Extensions-Verzeichnis und wurde in .ini aktiviert, aber php -m oder phpinfo() zeigt das Modul nicht an?
  • A:
    • Meistens: Das PHP-Paket in ServBay wurde noch nicht neugestartet. Nach jeder .ini-Änderung unbedingt das PHP-Paket in der ServBay-Oberfläche oder per Kommandozeile neu starten. Ein bloßes Neuladen des Browsers oder Webservers reicht nicht aus!
    • Überprüfen Sie die .ini-Datei auf Tipp- oder Syntaxfehler (korrekt: extension=modulename.so).
    • Kontrollieren Sie, ob der Wert von extension_dir in der php.ini korrekt ist. make install richtet sich nach der Ausgabe von php-config --extension-dir.
    • Ist die Modul-File beschädigt oder nicht kompatibel? Kompilieren Sie alles erneut und prüfen Sie, dass PHP- und Modul-Version zueinander passen. Schauen Sie auch in die Logs unterhalb des ServBay-Verzeichnisses, falls Fehlermeldungen zum Modul ein Problem anzeigen.

Fazit

Wenn Sie die in dieser Anleitung beschriebenen Schritte befolgen, können Sie individuelle PHP-Module (wie imagick oder sqlsrv) erfolgreich in Ihre ServBay macOS-Umgebung einbinden. Die wichtigsten Erfolgsfaktoren lauten:

1. Vollständige und korrekte Initialisierung der ServBay-Build-Umgebung.
2. Eindeutige Versionsangabe für phpize und php-config; stets den vollständigen Pfad zur gewünschten PHP-Version verwenden.
3. Alle externen Modulabhängigkeiten im Vorfeld klären und korrekt im Buildvorgang (über Umgebungsvariablen wie LDFLAGS, CPPFLAGS oder Custom-Konfigurationsparameter) angeben.
4. Module richtig aktivieren: Im Zielverzeichnis der PHP-Installation innerhalb von conf.d jeweilige .ini-Dateien erstellen oder anpassen und mit extension=modulename.so das Modul laden.
5. Das entsprechende PHP-Paket in ServBay nach jeder Änderung immer neu starten.

ServBay ist als umfassende lokale Entwicklungsumgebung äußerst flexibel und unterstützt eine Vielzahl von Technologien, darunter neben PHP und deren Modulen auch vollständige Setups für MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust und mehr. Darüber hinaus stehen praktische Features zur Verfügung, etwa das Beziehen von SSL-Zertifikaten via ACME, einfache CORS-Konfiguration, automatische Datensicherung (inklusive Einstellungen, Websites, Datenbanken, SSL-Zertifikate), Zurücksetzen des root-Datenbankpassworts sowie eigene CA-Zertifikate für lokales HTTPS.

Mit diesem Leitfaden können Sie Ihre lokale ServBay-PHP-Umgebung zielgerichtet erweitern und Ihre Webentwicklung noch effizienter gestalten. Bei weiterführenden Fragen ziehen Sie bitte die offizielle ServBay-Dokumentation oder die Community zu Rate.