Comment charger une extension PHP tierce dans ServBay

ServBay est un environnement de développement Web local puissant qui intègre de nombreux modules PHP fréquemment utilisés. En général, les utilisateurs peuvent simplement configurer et activer les extensions souhaitées via Packages -> Langages -> Version PHP -> Extensions dans l’interface de ServBay.

Cependant, il arrive que les développeurs aient besoin de charger des extensions PHP tierces ou compilées sur mesure qui ne sont pas incluses par défaut dans ServBay. Ce guide vous explique en détail comment charger de telles extensions pour une version spécifique de PHP dans ServBay, en prenant l’exemple de ionCube Loader. La méthodologie décrite s’applique également à d’autres extensions Zend ou à vos propres fichiers .so compilés.

Remarque importante concernant les extensions Zend : ionCube Loader est une extension Zend, qui interagit plus profondément avec le Zend Engine de PHP. Lors de la configuration, il est donc nécessaire d’utiliser la directive zend_extension au lieu de la directive extension destinée aux extensions classiques. Veillez à bien faire la distinction et à utiliser la directive appropriée.

Prérequis

• Vous avez installé et exécutez ServBay sur votre Mac (macOS).
• Vous disposez des droits administrateur, avec accès aux fichiers système et aux paramètres de configuration ServBay.
• Vous êtes à l’aise avec le Terminal de macOS.
• Vous vous êtes assuré que le fichier d’extension PHP tierce à charger (généralement un fichier .so) est entièrement compatible avec la version cible de PHP dans ServBay, l’architecture (Intel ou Apple Silicon) et les options de compilation (NTS/ZTS).

Attention : la compatibilité d’architecture est cruciale

ServBay fournit des paquets PHP natifs aussi bien pour l’architecture Intel (x86_64) que pour Apple Silicon (ARM64, par ex. puces M1/M2/M3/M4). Lors du chargement d’un fichier d’extension .so, il est impératif que l’architecture du fichier soit identique à celle du paquet PHP ServBay correspondant.

Il est impossible de mélanger des architectures différentes — une incompatibilité causera un échec ou un crash du démarrage de PHP.

Vous pouvez utiliser la commande file afin de déterminer l’architecture d’un exécutable ou d’un fichier .so :

1. Vérifier l’architecture du binaire PHP fourni par ServBay (remplacez 8.3 par votre version cible) :

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

   Exemple de sortie :

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

   ou

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

2. Vérifier l’architecture du fichier d’extension tierce (remplacez xdebug.so par le nom de votre extension) :

   file xdebug.so

   Exemple de sortie :

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

   ou

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

   Assurez-vous que l’architecture indiquée à l’étape 1 et l’étape 2 corresponde parfaitement.

Étapes à suivre

Étape 1 : Télécharger l’extension tierce (ex : ionCube Loader)

1. Rendez-vous sur la page de téléchargement officielle d’ionCube Loader. Sélectionnez la version adaptée à l’architecture de votre Mac. Pour macOS ARM64 (puces Apple Silicon M), téléchargez la version Darwin ARM64. Par exemple : https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz (Vérifiez toujours sur le site officiel que cette adresse est la dernière à jour.)
2. Après téléchargement, vous obtenez une archive .tar.gz (par exemple ioncube_loaders_dar_arm64.tar.gz).

Étape 2 : Identifier la version de PHP cible et le répertoire d’extensions ServBay

1. Ouvrez l’application ServBay.

2. Dans la barre de navigation à gauche, cliquez sur Packages puis Langages.

3. Dans la liste de droite, repérez la version de PHP pour laquelle vous souhaitez installer ionCube Loader (par exemple PHP 8.3) et retenez bien ce numéro de version.

4. Trouvez le répertoire d’installation des extensions pour cette version (extension_dir). C’est l’endroit où placer le fichier .so. La localisation exacte dépend du dossier d’installation de ServBay, de la version PHP, et des options de compilation.

   La méthode la plus fiable : via le Terminal.

   Ouvrez le Terminal et exécutez (adaptez /Applications/ServBay/package/php/8.3/current/bin/php à votre installation réelle) :

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

   La sortie donne une ligne comme extension_dir => /path/to/extension/directory. Exemple :

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

   Notez rigoureusement ce chemin pour l’étape suivante.

Étape 3 : Décompresser et placer le fichier Loader

1. Ouvrez le Terminal.

2. Allez dans le dossier où vous avez téléchargé l’archive .tar.gz (généralement ~/Downloads) :

   cd ~/Downloads

3. Décompressez l’archive :

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Vous obtenez alors un nouveau dossier ioncube.

4. Accédez au dossier ioncube :

   cd ioncube

5. Dans ce dossier, localisez le fichier .so correspondant à votre version PHP (ex : ioncube_loader_dar_8.3.so pour PHP 8.3).

6. Copiez ce fichier dans le répertoire d’extensions déterminé à l’étape 2. Exemple :

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

   • Veillez à adapter le chemin de destination à celui retourné par la commande php -i à l’étape 2.
   • Vérifiez bien de copier le fichier correspondant exactement à la bonne version et architecture de PHP.

Étape 4 : Configurer PHP dans ServBay

1. Retournez dans l’application ServBay.

2. Assurez-vous d’être dans Langages puis, à droite, cliquez sur la version de PHP cible (ex: PHP 8.3).

3. Dans la partie droite, ouvrez l’onglet PHP.

4. Faites défiler jusqu’au champ de texte Additional Parameters (Paramètres supplémentaires).

5. Ajoutez-y la ligne suivante :

   zend_extension = ioncube_loader_dar_8.3.so

   • Important : Remplacez ioncube_loader_dar_8.3.so si besoin par le nom réel placé dans le dossier d’extensions.
   • Utilisez zend_extension (et non extension) car il s’agit d’une extension Zend.
   • Comme le fichier est dans extension_dir, seul le nom de fichier suffit.
   • S’il y a déjà d’autres directives, ajoutez-en une nouvelle ligne.

   (Le visuel est un exemple — l’apparence réelle peut varier selon la version.)

6. Cliquez sur Enregistrer en bas à droite.

Étape 5 : Redémarrage du service PHP

Après avoir cliqué sur Enregistrer, ServBay détecte la modification et tente automatiquement de redémarrer PHP de manière transparente. Normalement aucune action manuelle supplémentaire n’est requise.

Étape 6 : Vérifier que le chargement a réussi

Deux méthodes courantes permettent de vérifier si ionCube Loader est bien activé :

1. Via la ligne de commande :

   • Ouvrez le Terminal.

   • Exécutez la commande suivante (en indiquant le chemin correct vers la version de PHP concernée) :

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

     Si le chargement est correct, vous devriez voir une ligne du type ionCube Loader.

   • Vous pouvez aussi afficher la version PHP, ce qui dévoile généralement la présence d’ionCube Loader juste sous la version du Zend Engine :

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

     Exemple de sortie si ionCube Loader est actif (les numéros de version peuvent différer) :

     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.

     À noter la ligne with the ionCube PHP Loader ....

2. Via la fonction phpinfo():

   • Dans la racine de votre site local (par exemple /Applications/ServBay/www/servbay.demo/ ou un autre dossier), créez un fichier PHP, ex : info.php.
   • Son contenu doit être :

     <?php
     phpinfo();
     ?>

   • Rendez-vous sur ce fichier depuis votre navigateur, ex : http://servbay.demo/info.php (adaptez le domaine si besoin).
   • Sur la page phpinfo(), faites une recherche "ionCube" (Cmd+F ou Ctrl+F). Si tout fonctionne, un bloc d’informations propre à ionCube Loader apparait avec details de version, licence, etc.

Si ces vérifications affichent les informations d’ionCube Loader, l’extension est opérationnelle.

Problèmes courants et diagnostic

• PHP ne démarre pas ou plante : Très souvent dû à une incompatibilité d’architecture entre le fichier d’extension et le paquet PHP. Vérifiez minutieusement selon les étapes du chapitre Prérequis. Des incompatibilités de version ou de compilation PHP peuvent aussi poser problème.
• Chemin extension_dir incorrect : Veillez à placer le .so exactement dans le répertoire retourné par la commande php -i | grep extension_dir.
• Erreur de configuration : Vérifiez la directive ajoutée dans Additional Parameters de ServBay. Pour les extensions Zend, la syntaxe doit être zend_extension = fichier.so; pour les extensions classiques, c’est extension = fichier.so. Le nom de fichier doit être rigoureusement identique à celui copié (sensible à la casse).
• Problèmes de droits d'accès : Assurez-vous que l’utilisateur ServBay (votre utilisateur macOS habituel) a bien les droits de lecture sur le fichier .so et son dossier parent. Sauf modification manuelle, cela ne pose en général pas de souci, mais c’est à vérifier en cas de blocage.
• ServBay non redémarré : Bien que ServBay redémarre normalement PHP après modification, si le changement ne prend pas effet, forcez le redémarrage des services ou de l’application.
• Aucune info dans phpinfo() : Vérifiez que vous consultez bien le fichier sur le bon site ET avec la bonne version PHP où l’extension est activée.

Conclusion

En suivant scrupuleusement ce guide, vous pourrez charger avec succès une extension comme ionCube Loader ou tout autre module PHP tierce au format .so pour une version spécifique de PHP administrée par ServBay. L’essentiel est de bien identifier la version cible, de localiser le répertoire d’extensions correct (extension_dir), d’y placer un fichier compatible en architecture et version, puis de référencer le nom du fichier dans les Paramètres supplémentaires de la configuration ServBay à l’aide de la directive adéquate (zend_extension ou extension). En cas de difficulté, appuyez-vous sur la section de dépannage, en prêtant une attention particulière à la correspondance d’architecture et aux chemins de fichiers.