Wie man in ServBay Drittanbieter-PHP-Erweiterungen lädt

ServBay ist eine leistungsstarke lokale Web-Entwicklungsumgebung, die viele gängige PHP-Erweiterungen bereits integriert. Normalerweise können Nutzer gewünschte Erweiterungen einfach über Pakete (Packages) -> Sprachen (Languages) -> PHP-Version -> Erweiterungen in ServBay konfigurieren und aktivieren.

Entwickler benötigen jedoch manchmal weitere, in ServBay nicht enthaltene PHP-Erweiterungen von Drittanbietern oder eigens kompilierte Erweiterungen. Dieser Leitfaden beschreibt Schritt für Schritt, wie Sie solche Erweiterungen für eine bestimmte PHP-Version in ServBay laden – demonstriert am Beispiel des ionCube Loaders. Das Verfahren gilt auch für andere Zend-Erweiterungen oder selbstkompilierte .so-Dateien.

Wichtiger Hinweis zu Zend-Erweiterungen: Der ionCube Loader ist eine Zend-Erweiterung und interagiert besonders tief mit der Zend Engine von PHP. Daher muss beim Konfigurieren die Direktive zend_extension verwendet werden, statt der für Standard-Erweiterungen üblichen Direktive extension. Bitte unterscheiden Sie dies genau und verwenden die richtige Anweisung.

Voraussetzungen

• ServBay ist auf Ihrem macOS-System installiert und läuft bereits.
• Sie verfügen über Administratorrechte und können auf Systemdateien sowie das ServBay-Konfigurationsmenü zugreifen.
• Sie sind mit der macOS-Terminal-App vertraut.
• Sie haben die benötigte Drittanbieter-PHP-Erweiterung (meist eine .so-Datei) vorliegen und sie ist vollständig kompatibel mit PHP-Version, Architektur (Intel oder Apple Silicon) und Build-Optionen (wie NTS/ZTS) Ihrer Zielumgebung in ServBay.

Hinweis: Architekturkompatibilität ist entscheidend

ServBay bietet native PHP-Pakete sowohl für Intel (x86_64) als auch für Apple Silicon (ARM64, z. B. M1/M2/M3/M4) an. Beim Laden einer .so-Erweiterungsdatei müssen Sie unbedingt sicherstellen, dass die Kompilierungsarchitektur dieser Datei exakt mit der Architektur des jeweiligen PHP-Pakets in ServBay übereinstimmt.

Dateien unterschiedlicher Architektur dürfen nicht gemischt werden – eine abweichende Architektur führt dazu, dass PHP nicht startet oder abstürzt!

Sie können den Befehl file verwenden, um die Architektur von ausführbaren Dateien oder .so-Dateien zu überprüfen:

1. Ermitteln Sie die Architektur des in ServBay enthaltenen PHP-Pakets (ersetzen Sie 8.3 durch Ihre tatsächliche PHP-Version):

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

   Beispielausgabe:

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

   oder

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

2. Überprüfen Sie die Architektur Ihrer heruntergeladenen oder kompilierten .so-Erweiterungsdatei (ersetzen Sie xdebug.so durch Ihren Dateinamen):

   file xdebug.so

   Erwartete Ausgabe:

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

   oder

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

   Die Architektur in Schritt 1 und Schritt 2 muss exakt übereinstimmen.

Schritt-für-Schritt-Anleitung

Schritt 1: Drittanbieter-Erweiterung herunterladen (am Beispiel ionCube Loader)

1. Rufen Sie die offizielle Download-Seite des ionCube Loaders auf. Wählen Sie die passende Version entsprechend Ihrer macOS-Architektur. Für macOS ARM64 (Apple Silicon M-Serie) laden Sie die Version für Darwin ARM64 herunter. Sie können direkt den folgenden Link nutzen – achten Sie aber darauf, auf der Webseite nach neueren Versionen zu schauen (dies ist ein Beispiel-Download): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Nach Abschluss des Downloads erhalten Sie eine .tar.gz-Archivdatei, z. B. ioncube_loaders_dar_arm64.tar.gz.

Schritt 2: Ziel-PHP-Version und Erweiterungsverzeichnis von ServBay bestimmen

1. Starten Sie die ServBay-Anwendung.

2. Klicken Sie im linken Navigationsbereich unter Pakete (Packages) auf Sprachen (Languages).

3. Suchen Sie rechts die PHP-Version, für die Sie den ionCube Loader installieren möchten (z. B. PHP 8.3), und notieren Sie sich die Versionsnummer.

4. Ermitteln Sie das Erweiterungsverzeichnis (extension_dir) dieser PHP-Version in ServBay. Hierhin gehören die .so-Dateien. Der genaue Pfad hängt vom Installationsort, der PHP-Version sowie Build-Optionen ab.

   Die zuverlässigste Methode ist die Terminalabfrage:

   Öffnen Sie die Terminal-App und führen Sie diesen Befehl aus (ersetzen Sie /Applications/ServBay/package/php/8.3/current/bin/php ggf. durch den Pfad Ihrer gewünschten PHP-Version):

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

   Die Ausgabe zeigt extension_dir => /pfad/zum/erweiterungsverzeichnis. Zum Beispiel:

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

   Notieren Sie sich den Pfad, Sie benötigen ihn im weiteren Verlauf.

Schritt 3: Loader-Datei entpacken und ablegen

1. Öffnen Sie die Terminal-App.

2. Navigieren Sie per cd-Befehl in das Verzeichnis, in dem Sie das .tar.gz-Archiv heruntergeladen haben (meist ~/Downloads):

   cd ~/Downloads

3. Entpacken Sie die Datei:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Dadurch wird im aktuellen Verzeichnis ein neuer Ordner ioncube erstellt.

4. Wechseln Sie in dieses Verzeichnis:

   cd ioncube

5. Dort sehen Sie .so-Dateien für verschiedene PHP-Versionen, z. B. ioncube_loader_dar_8.3.so. Suchen Sie die Datei, die exakt Ihrer PHP-Version entspricht (wie in Schritt 2 ermittelt).

6. Kopieren Sie die passende .so-Datei in das in Schritt 2 ermittelte Erweiterungsverzeichnis. Angenommen, dieses lautet /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ und Sie möchten den Loader für PHP 8.3 installieren:

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

   • Ersetzen Sie den Zielpfad /Applications/ServBay/.../no-debug-non-zts-20230831/ unbedingt durch den tatsächlich per php -i ermittelten Erweiterungsverzeichnispfad.
   • Achten Sie darauf, dass die Datei exakt zur PHP-Version passt und deren Architektur entspricht (siehe Voraussetzungen).

Schritt 4: PHP in ServBay konfigurieren

1. Wechseln Sie zurück zur ServBay-Oberfläche.

2. Stellen Sie sicher, dass Sprachen (Languages) gewählt ist, und klicken Sie rechts auf die gewünschte PHP-Version (z. B. PHP 8.3).

3. Öffnen Sie im rechten Bereich den Tab PHP.

4. Scrollen Sie nach unten zum Textfeld Additional Parameters (Zusätzliche Parameter).

5. Fügen Sie hier die folgende Zeile hinzu, um den ionCube Loader zu laden:

   zend_extension = ioncube_loader_dar_8.3.so

   • Wichtig: Ersetzen Sie ioncube_loader_dar_8.3.so durch den tatsächlichen Dateinamen, den Sie ins Erweiterungsverzeichnis kopiert haben.
   • Verwenden Sie unbedingt zend_extension, nicht extension, da es sich um eine Zend-Erweiterung handelt.
   • Sie brauchen nur den Dateinamen anzugeben, keinen vollständigen Pfad, weil die Datei bereits im extension_dir liegt.
   • Falls das Feld bereits andere Einträge enthält, einfach eine neue Zeile anfügen.

   (Screenshot dient nur zur Veranschaulichung; die tatsächliche Oberfläche kann je nach Version abweichen)

6. Klicken Sie unten rechts auf Save, um die Konfiguration zu speichern.

Schritt 5: PHP-Dienst neu starten

Nach Klick auf Save erkennt ServBay die geänderte Konfiguration automatisch und startet die betroffenen Dienste (inklusive PHP) in der Regel selbstständig neu. Manuelle Neustarts sind in der Regel nicht nötig.

Schritt 6: Überprüfen, ob die Erweiterung erfolgreich geladen wurde

Sie können die erfolgreiche Einbindung des ionCube Loaders auf zwei Arten prüfen:

1. Prüfung via Terminal:

   • Öffnen Sie das Terminal.

   • Führen Sie den folgenden Befehl aus, um die geladenen PHP-Module aufzulisten (achten Sie darauf, mit dem kompletten Pfad der richtigen PHP-Version zu arbeiten):

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

     Bei erfolgreichem Laden erscheint eine Zeile wie ionCube Loader.

   • Alternativ zeigt auch der Befehl php -v in der Regel nach erfolgreichem Laden unterhalb der Zend-Engine-Informationen einen Eintrag für den ionCube Loader:

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

     Beispielausgabe nach erfolgreicher Integration (Versionsnummern ggf. abweichend):

     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.

     Achten Sie auf die Zeile with the ionCube PHP Loader ....

2. Prüfung via phpinfo():

   • Legen Sie im Root-Verzeichnis Ihrer Website (z. B. /Applications/ServBay/www/servbay.demo/ oder einem anderen von Ihnen angegebenen Pfad) eine neue PHP-Datei an, beispielsweise info.php.
   • Der Inhalt der Datei sollte nur lauten:

     <?php
     phpinfo();
     ?>

   • Rufen Sie diese Datei im Browser auf, z. B. über http://servbay.demo/info.php (setzen Sie Ihren lokalen Webseitennamen ein).
   • Suchen Sie auf der ausgegebenen phpinfo()-Seite nach "ionCube" (über die Suchen-Funktion des Browsers: meist Cmd + F oder Ctrl + F). Ist der Loader erfolgreich geladen, finden Sie einen entsprechenden Block über ionCube Loader mit Versions- und Lizenzinformationen.

Wenn bei der Prüfung ionCube Loader-Informationen angezeigt werden, ist die Erweiterung erfolgreich geladen.

Häufige Probleme und Fehlerbehebung

• PHP startet nicht oder stürzt ab: Die häufigste Ursache hierfür ist eine nicht übereinstimmende Architektur zwischen Erweiterungsdatei und PHP-Paket. Überprüfen Sie beides sorgfältig wie im Abschnitt „Voraussetzungen“ beschrieben. Auch inkonsistente PHP-Versionen oder Build-Optionen können Fehler verursachen.
• Falscher extension_dir-Pfad: Die .so-Datei muss wirklich in das für diese PHP-Version bestimmte ServBay-Erweiterungsverzeichnis kopiert werden – der mit php -i | grep extension_dir ermittelte Pfad ist maßgeblich.
• Fehlerhafte Konfigurationsanweisung: Prüfen Sie die Anweisung in Additional Parameters in ServBay genau. Zend-Erweiterungen benötigen zwingend zend_extension = dateiname.so; Standard-Erweiterungen werden via extension = dateiname.so geladen. Der Dateiname muss exakt (inklusive Groß-/Kleinschreibung) mit dem im extension_dir abgelegten übereinstimmen.
• Dateirechte: Der ServBay-Benutzer (in der Regel Ihr macOS-User) braucht Lesezugriff auf die .so-Datei und deren Verzeichnis. Normalerweise entstehen durch das Kopieren keine Rechteprobleme, allerdings sollten veränderte Rechte kontrolliert werden.
• ServBay wurde nicht neu gestartet: Meistens übernimmt ServBay den Neustart automatisch. Falls die Änderungen dennoch nicht greifen, stoppen und starten Sie gegebenenfalls die betroffenen Dienste oder die gesamte Anwendung erneut.
• Keine Informationen im phpinfo()-Output: Prüfen Sie, ob Sie tatsächlich die von ServBay verwaltete PHP-Instanz samt korrekt konfigurierter Erweiterung aufrufen. Bei mehreren PHP-Versionen oder Websites kann es leicht zu Verwechslungen kommen.

Fazit

Wenn Sie die oben stehenden Schritte befolgen, können Sie für eine bestimmte, von ServBay verwaltete PHP-Version erfolgreich den ionCube Loader oder andere Drittanbieter-Erweiterungen im .so-Format einbinden. Entscheidend ist, die Ziel-PHP-Version klar zu bestimmen, das richtige Erweiterungsverzeichnis (extension_dir) zu ermitteln, eine kompatible Erweiterungsdatei zu platzieren und in den Additional Parameters von ServBay mit der passenden Anweisung (zend_extension oder extension) einzutragen. Bei Problemen hilft der Fehlerbehebungsbereich; achten Sie besonders auf Architekturkompatibilität und Dateipfade.