Benutzerdefinierte PHP-Module in ServBay kompilieren und installieren

ServBay ist eine leistungsstarke lokale Web-Entwicklungsumgebung, die macOS und Windows unterstützt und zahlreiche Softwarepakete integriert, um den Anforderungen moderner Webentwickler gerecht zu werden. Es enthält vorkonfigurierte Technologien wie PHP, Node.js, Python, Go, Java, Datenbanken (z.B. MySQL, PostgreSQL, MongoDB), Caches (Redis) und Webserver (Caddy, Nginx, Apache). ServBay bietet für jedes Softwarepaket Multiversions-Support, sodass Sie Ihre Umgebung flexibel je nach Projektanforderung wechseln können.

Obwohl ServBay viele gebräuchliche PHP-Module bereits enthält, kann es vorkommen, dass Sie zusätzliche PHP-Module kompilieren und installieren müssen, um die Funktionalität von PHP zu erweitern oder spezielle Drittanbieter-Dienste einzubinden.

In diesem Leitfaden erfahren Sie Schritt für Schritt, wie Sie in ServBay für Ihre PHP-Version benutzerdefinierte Module kompilieren und installieren. Die Anleitung verwendet die populären Module imagick für Bildverarbeitung und sqlsrv als Microsoft SQL Server Treiber als Praxisbeispiele, damit Sie die gewünschten Funktionen einfach zum lokalen ServBay PHP-Umfeld hinzufügen können.

Voraussetzungen

Wichtiger Hinweis

Bevor Sie mit dem Kompilieren beliebiger PHP-Module beginnen, ist der wichtigste Schritt die Initialisierung der ServBay-Kompilierungsumgebung und die korrekte Konfiguration der System-Umgebungsvariablen gemäß der offiziellen ServBay-Dokumentation. Dies ist die grundlegende Voraussetzung für eine erfolgreiche Kompilierung jeglicher Pakete (einschließlich PHP-Erweiterungen) in ServBay. Falls Sie diesen Schritt überspringen oder Fehler dabei machen, werden die folgenden Kompilierungsschritte höchstwahrscheinlich fehlschlagen – typischerweise mit Fehlermeldungen zu fehlenden Befehlen, Bibliotheken oder Header-Dateien.

Das Initialisierungsskript der ServBay-Kompilierungsumgebung setzt alle notwendigen Umgebungsvariablen, wie z.B. PATH (zeigt auf die internen ServBay-Build-Tools), SERVBAY_PACKAGE_FULL_PATH (der Pfad zum ServBay-Paket-Root) und CPU_NUMBER (für parallele Kompilierung). Diese Variablen sind für die folgenden Kompilierbefehle essenziell.

Detaillierte Informationen zur Initialisierung der ServBay-Kompilierungsumgebung finden Sie in der Dokumentation: Pakete mit ServBay kompilieren. Vergewissern Sie sich, dass Sie die Anweisungen vollständig verstanden und korrekt umgesetzt haben.

Bevor Sie mit der Modul-Kompilierung fortfahren, stellen Sie sicher, dass die oben beschriebenen Initialisierungsschritte erfolgreich abgeschlossen und alle relevanten Umgebungsvariablen in Ihrer aktuellen Terminal-Session gesetzt wurden.

Bedeutung der PHP-Version Auswahl

Ein Hauptmerkmal von ServBay ist die Unterstützung mehrerer paralleler PHP-Versionen auf demselben System. Diese Flexibilität erleichtert Entwicklern den Wechsel der PHP-Umgebung für verschiedene Projekte. Wenn Sie ein PHP-Modul kompilieren möchten, müssen Sie dies immer für eine bestimmte PHP-Version tun. Die Tools phpize und php-config, die zur Kompilierungsvorbereitung und zum Abrufen von Versions-Konfigurationsdaten genutzt werden, sind immer mit einer spezifischen PHP-Version verknüpft.

• phpize: Ein Skript zur Vorbereitung der Kompilierungsumgebung für PHP-Erweiterungen. Es liest die Datei config.m4 und erstellt daraus ein Standard-configure-Skript – der erste Schritt für die Kompilierung von C/C++-Software.
• php-config: Das Skript liefert detaillierte Konfigurationsinfos zur jeweiligen PHP-Version, wie Compiler-Flags, Include-Verzeichnisse, Bibliothekspfade und das Erweiterungsinstallationsverzeichnis. Das configure-Skript ruft php-config auf, um einen korrekten Modul-Build und Link zur jeweiligen PHP-Version sicherzustellen.

Daher müssen Sie beim Einsatz von phpize, php-config oder anderen Build-Befehlen stets den vollständigen Pfad angeben, der exakt zu der PHP-Version gehört, für die Sie das Modul kompilieren möchten.

Beispiel für Pfadangaben

Möchten Sie beispielsweise ein Modul für PHP 8.3 in ServBay kompilieren:

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

Nur die exakte Versionsauswahl garantiert die Kompatibilität der kompilierten Module mit dem Ziel-PHP, und verhindert Kompilierungsfehler oder Laufzeitprobleme wie „Symbol not found“.

Die folgenden Beispiele aus dieser Anleitung beziehen sich auf die installierte PHP-Version 8.3 in ServBay. Bitte ersetzen Sie in der Praxis die benutzten Pfade jeweils mit denen Ihrer tatsächlichen Ziel-PHP-Version in ServBay.

Kompilieren des PHP imagick-Moduls

imagick ist eine populäre PHP-Erweiterung für anspruchsvolle Bildverarbeitung und basiert auf der leistungsstarken ImageMagick-Bibliothek. Mit imagick können Sie direkt in PHP komplexe Bildoperationen wie Skalierungen, Zuschnitte, Formatkonvertierungen, Wasserzeichen, Bildzusammenstellungen u.v.m. durchführen. Dies sind die vollständigen Schritte zur Kompilierung und Installation des imagick-Moduls für eine bestimmte ServBay-PHP-Version:

Schritt 1: Installation der ImageMagick-Bibliothek

Das imagick-Modul setzt voraus, dass die ImageMagick-Bibliothek auf dem System vorhanden ist.

macOS

Empfohlen wird die Installation per Homebrew Paketmanager. Falls Sie Homebrew noch nicht installiert haben, finden Sie eine Anleitung auf der Homebrew Website.

Terminal öffnen und folgenden Befehl ausführen, um ImageMagick inklusive Entwicklertools zu installieren:

brew install imagemagick

Windows

Windows-Nutzer müssen ImageMagick manuell herunterladen und installieren. Gehen Sie dazu auf die offizielle ImageMagick Downloadseite und wählen Sie die passende Version aus.

Vergewissern Sie sich, dass Sie die Version mit Entwicklertools installieren und den Installationspfad der Umgebungsvariablen hinzufügen.

Schritt 2: Quellcode des imagick-Moduls beschaffen

Laden Sie als nächstes den Quellcode des imagick-Moduls von der offiziellen PECL-Website herunter. Auf der PECL imagick Seite finden Sie die jeweils aktuelle Version (meist die empfohlene stabile Version). Beispielhaft wird in diesem Leitfaden die Version 3.7.0 verwendet:

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

Schritt 3: Quellpaket entpacken und Verzeichnis wechseln

Nach dem Download entpacken Sie das Quellpaket und wechseln in das Verzeichnis mit folgendem Befehl:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Schritt 4: Kompilierungsumgebung vorbereiten (phpize einsetzen)

Wechseln Sie in das Quellverzeichnis und führen Sie das zum Ziel-PHP passende phpize-Tool aus. Wie oben dargestellt, verwenden Sie unbedingt den vollständigen Pfad Ihrer PHP-Version (hier z.B. PHP 8.3, wobei die Variable SERVBAY_PACKAGE_FULL_PATH vorab gesetzt sein muss):

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

Wurde phpize erfolgreich ausgeführt, prüft es die config.m4 und generiert das configure-Skript und andere nötige Builddateien. Die Terminalausgabe informiert Sie darüber, sobald die Buildumgebung bereit ist.

Schritt 5: Build-Konfiguration festlegen

Führen Sie das eben erstellte configure-Skript aus, um die Build-Optionen zu konfigurieren. Sie müssen die --with-php-config-Option verwenden, um den PHP-Konfigurationspfad exakt für Ihre Zielversion zu setzen.

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

Das Skript prüft alle Voraussetzungen, findet die ImageMagick-Bibliothek und nötigen Header, und erstellt aus den PHP-Konfigurationsdaten das endgültige Makefile. Kommt es zu Fehlern, fehlen meist Systemabhängigkeiten oder es liegen falsche Pfade vor.

Schritt 6: Modul kompilieren und installieren

Ist die Konfiguration ohne Fehler gelaufen und das Makefile erstellt, starten Sie die Kompilierung mit:

make -j ${CPU_NUMBER}
make install

Das make install-Kommando kopiert das fertige Modul automatisch in das Standard-Erweiterungsverzeichnis der gewählten PHP-Version:

• 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\

Pfadangaben variieren je nach PHP-Version und Build-Konfiguration.

Schritt 7: Modul aktivieren

Ist das Modul installiert, aktivieren Sie es in der Konfiguration der jeweiligen PHP-Version. ServBay bietet hierzu eine GUI-Methode:

• Öffnen Sie ServBay
• Navigieren Sie im Menü links zu Sprachen - PHP - PHP 8.3
• Rechts wählen Sie den Reiter PHP aus, scrollen bis zum Abschnitt „Weitere Parameter“ und geben dort extension=imagick.so ein
• Speichern Sie, ServBay startet den PHP-Prozess automatisch neu und liest das neue Modul ein

Schritt 8: Modul-Ladung überprüfen

Nach der Aktivierung starten Sie das PHP-Paket in ServBay neu, damit die Konfiguration wirksam wird. Das geht über das ServBay-Panel per Knopfdruck oder per ServBay-Kommandozeilentool (Befehle siehe Dokumentation).

Nach dem Neustart prüfen Sie am besten im Terminal, ob das imagick-Modul geladen wird:

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

Nutzen Sie den exakten Binärpfad zu Ihrer PHP-Version. Mit -m werden alle geladenen Module angezeigt. Taucht imagick im Output auf, ist das Modul aktiv.

Eine ausführlichere Kontrolle erreichen Sie mit einer PHP-Datei (info.php) im Webroot, die folgenden Code enthält: <?php phpinfo(); ?>. Webroot-Standardpfade sind:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Rufen Sie die Datei dann per Browser auf, z.B. unter http://localhost/info.php. Suchen Sie auf der PHPInfo-Seite nach „imagick“, um die Modulaktivierung und Version zu verifizieren.

Kompilieren der Module PHP sqlsrv / pdo_sqlsrv

Die Module sqlsrv und pdo_sqlsrv sind offizielle PHP-Erweiterungen zur Verbindung und Steuerung von Microsoft SQL Server-Datenbanken. Sie bauen auf den von Microsoft bereitgestellten ODBC-Treibern auf. Wer mit ServBay und PHP auf SQL Server zugreifen möchte, benötigt diese Module. Im Folgenden die notwendigen Schritte zur Kompilierung und Installation von sqlsrv und pdo_sqlsrv:

Hinweis: Wichtige Voraussetzungen

Bevor Sie das sqlsrv-Modul kompilieren und installieren, müssen Sie zuerst die Microsoft SQL Server ODBC-Treiber und Tools bereitstellen. Diese Pakete sind nicht Teil von ServBay und müssen manuell installiert werden.

macOS

Die Installation erfolgt idealerweise per Homebrew. Ist Homebrew noch nicht verfügbar, besuchen Sie die Homebrew-Website.

Installieren Sie ODBC-Treiber und Tools von Microsoft mit folgenden Homebrew-Befehlen (Lizenzvereinbarung muss oft über die Umgebungsvariable HOMEBREW_ACCEPT_EULA=Y bestätigt werden):

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

Die Pakete werden typischerweise nach /opt/homebrew/ (Apple Silicon Macs) oder /usr/local/ (Intel Macs) installiert. Pfade müssen beim Build korrekt angegeben werden.

Windows

Windows-Nutzer erhalten den ODBC Driver über die Microsoft ODBC Driver für SQL Server Website:

• Passenden Treiber herunterladen und installieren
• Nach Installation prüfen, ob der Treiber systemweit verfügbar ist

Klären Sie daher vor der Kompilierung des sqlsrv-Moduls, ob alle Abhängigkeiten installiert sind.

Tipp

sqlsrv und pdo_sqlsrv sind zwei getrennte Module, die getrennt kompiliert werden müssen – der Ablauf ist nahezu identisch. Nachfolgend erfolgen die Schritte am Beispiel von sqlsrv.

Schritt 1: Microsoft ODBC-Treiber und Tools installieren

(Vgl. oben: mit Homebrew msodbcsql18 und mssql-tools18 installieren.)

Schritt 2: Quellcode für sqlsrv-Modul beziehen

Über die PECL-Website laden Sie die Quellpakete für sqlsrv und pdo_sqlsrv. Aktuelle Links finden Sie auf der PECL sqlsrv Seite. Beispielhaft wird Version 5.12.0 verwendet:

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

Nach Download Quellpaket entpacken und in das Modulverzeichnis wechseln:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Für pdo_sqlsrv nach gleichem Schema, die folgenden Schritte erfolgen beispielhaft für sqlsrv.

Schritt 4: Kompilierungsumgebung vorbereiten (phpize einsetzen)

Im Quellverzeichnis das passende phpize für die Ziel-PHP verwenden, etwa so:

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

Schritt 5: Build-Optionen konfigurieren (mit Abhängigkeits-Pfaden)

Das sqlsrv-Modul benötigt die von Homebrew installierten Microsoft ODBC-Treiber und unixODBC-Header. Vor dem Starten von ./configure setzen Sie die Umgebungsvariablen LDFLAGS und CPPFLAGS, um die Suchpfade für Bibliotheken und Header korrekt zu hinterlegen. Die Option --with-php-config gibt den zum Ziel-PHP gehörenden Konfigurationspfad vor.

Wählen Sie die richtigen Homebrew-Pfade – auf Intel Macs meist /usr/local, auf Apple Silicon Macs /opt/homebrew. Beispiel für /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 sorgt für Auffinden aller benötigten Header
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: Suchpfad des Linkers für Bibliotheken. -L/opt/homebrew/lib zeigt auf das Standardverzeichnis von Homebrew.
• CPPFLAGS: Pfade für C/C++ Präprozessor für Header-Dateien. -I/opt/homebrew/opt/unixodbc/include für unixODBC-Header; -I/opt/homebrew/include für weitere Header. ${CPPFLAGS} und ${LDFLAGS} erhalten vorherige Einstellungen aus der ServBay-Kompilierungsumgebung.

Schritt 6: Modul kompilieren und installieren

Läuft die Konfiguration fehlerfrei und das Makefile liegt vor, kompilieren und installieren Sie das Modul mit:

make -j ${CPU_NUMBER}
make install

Das make install-Kommando bringt das erzeugte Modul (z.B. sqlsrv.so und ggf. auch pdo_sqlsrv.so) in das korrekte PHP-Erweiterungsverzeichnis.

Schritt 7: Modul aktivieren

Nach der Installation wird das Modul in der PHP-Konfiguration der Zielversion aktiviert – ServBay bietet dafür eine GUI:

• ServBay öffnen
• Links im Menü zu Sprachen - PHP - PHP 8.3 navigieren
• Rechts unter dem Reiter PHP bis „Weitere Parameter“ scrollen und extension=sqlsrv.so sowie extension=pdo_sqlsrv.so eintragen
• Speichern – ServBay startet den PHP-Prozess automatisch neu und lädt das Modul

Schritt 8: Modul-Ladung überprüfen

Nach Aktivierung unbedingt das PHP-Paket in ServBay neu starten.

Modulladung testen Sie 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

Erscheinen sqlsrv und/oder pdo_sqlsrv im Output, ist das Modul aktiv. Auch mittels phpinfo() können Status und Konfigurationsdetails verifiziert werden.

FAQ – Häufige Probleme

• Frage: Beim Kompilieren erscheint „Cannot find autoconf“ oder ein ähnlicher Fehler?
  • Antwort: In nahezu allen Fällen ist die ServBay-Kompilierungsumgebung nicht korrekt initialisiert. Prüfen Sie nochmals Schritt „Voraussetzungen“ und folgen Sie der Anleitung Pakete mit ServBay kompilieren penibel. Vergewissern Sie sich, dass Buildtools wie autoconf, automake, libtool installiert und über die Umgebungsvariable referenziert werden. Oft reicht das Ausführen des ServBay-Initialisierungsskripts und ein Neustart des Terminals.
• Frage: Das configure-Skript schlägt fehl mit Meldung, dass eine Bibliothek oder ein Header fehlt?
  • Antwort: Es fehlen entweder Systembibliotheken oder Header – entweder gar nicht installiert oder der Pfad wird nicht gefunden:
    • Bei imagick: Prüfen Sie, ob das ImageMagick-Entwicklungspaket installiert ist (brew install imagemagick).
    • Bei sqlsrv: Kontrollieren Sie, ob die Microsoft ODBC-Treiber (msodbcsql18) und mssql-tools18 per Homebrew installiert wurden. Vor ./configure unbedingt LDFLAGS und CPPFLAGS variablen korrekt setzen, inkl. Homebrew-Pfade (/opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Prüfen Sie, ob in den ServBay-Konfigurationsumgebungen die Homebrew-Pfade enthalten sind und ob Sie ggf. das Homebrew-Binverzeichnis manuell zum PATH hinzufügen müssen.
• Frage: make oder make install schlagen fehl?
  • Antwort: Mögliche Gründe:
    • Fehlende Build-Abhängigkeiten: Fehleroutput genau lesen, es wird meist benannt, was fehlt. Entsprechende Pakete nachinstallieren.
    • Konfigurationsfehler: Prüfen Sie die Parameter von configure, insbesondere ob bei --with-php-config der korrekte Pfad Ihrer ServBay-PHP-Version gesetzt ist.
    • Berechtigungsprobleme: Beim Kopieren via make install in die PHP-Erweiterungsordner, kann es Berechtigungsprobleme geben. Notfalls sudo make install nutzen (Achtung: nur wenn Sie die Risiken kennen!).
    • Quellpaketprobleme: Prüfen Sie, ob das heruntergeladene Quellpaket vollständig und intakt ist.
• Frage: Die .so-Datei wurde generiert und liegt im Erweiterungsverzeichnis, ist im .ini aktiviert, aber bei php -m oder phpinfo() taucht das Modul nicht auf?
  • Antwort:
    • Sehr häufig: Das ServBay-PHP-Paket wurde nach der .ini-Änderung nicht neu gestartet. Sie müssen explizit via ServBay-Panel oder Kommandozeile das PHP-Paket der gewünschten Version neu starten! Einfaches Neuladen der Webseite oder Webserver-Neustart (z.B. Caddy/Nginx) reicht nicht, die PHP-Instanz muss neu gestartet werden.
    • Syntaxfehler in der .ini: Prüfen Sie die Einträge auf Tipp- oder Formatfehler (extension=modulename.so).
    • Falscher Erweiterungspfad: Kontrollieren Sie, ob die Option extension_dir in php.ini korrekt auf das Modulverzeichnis in ServBay zeigt. Der Pfad kann via php-config --extension-dir verifiziert werden.
    • Defektes Modul/Versioninkompatibilität: Modul einmal neu kompilieren. Prüfen Sie, ob das Quellpaket mit Ihrer PHP-Version kompatibel ist. Notfalls PHP-Logs unter ServBay prüfen (meist im logs-Verzeichnis), um Details zu Modul-Ladefehlern zu erhalten.

Zusammenfassung

Befolgen Sie die oben genannten Schritte sorgfältig, um in Ihrer ServBay-Entwicklungsumgebung benutzerdefinierte PHP-Module (wie imagick und sqlsrv) erfolgreich zu kompilieren und installieren. Der Schlüssel zum Erfolg liegt in:

1. Sorgfältiger Initialisierung der ServBay-Kompilierungsumgebung – zwingende Voraussetzung für alles Weitere.
2. Exakte Auswahl und Nutzung der Pfade zur Ziel-PHP-Version – insbesondere bei phpize und php-config.
3. Korrektes Handling der externen Modul-Abhängigkeiten – Installation von Bibliotheken/Tools wie ImageMagick, ODBC-Treiber; bei der Build-Konfiguration (./configure) korrekter Umgebungsvariablen- oder Parameter-Einsatz (LDFLAGS, CPPFLAGS, etc.).
4. Richtige Aktivierung des Moduls in der PHP-Konfiguration – Anlage/Änderung der .ini mit Eintrag extension=modulename.so.
5. Neustart des ServBay-PHP-Pakets – damit die neuen Erweiterungen tatsächlich geladen werden.

ServBay bietet als Komplettpaket für die lokale Entwicklung umfassende Flexibilität und unterstützt vielfältige Technologien: MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust und mehr. Nützliche Features wie ACME-SSL-Zertifikatbeantragung, bequeme CORS-Konfiguration, automatisierte Backups (von Einstellungen, Webseiten, Datenbanken, Zertifikaten), Zurücksetzen des root-Datenbankpassworts sowie ServBay User CA und Public CA für lokales HTTPS erleichtern den effizienten Aufbau eines modernen Entwicklungs-Workflows.

Wir hoffen, dass Ihnen diese Anleitung hilft, die notwendigen PHP-Funktionen in ServBay einfach zu ergänzen und produktiv Web-Applikationen zu entwickeln. Bei weiteren Fragen finden Sie Hilfe in der ServBay-Dokumentation oder der Community.