Formation PUB020 : WordPress, 2020 Aménager notre environnement pour travailler efficacement

Installer XDebug sur macOS Big Sur


XDebug est un outil très important pour les développeurs PHP.

Quand il est installé et que l'IDE - par exemple phpStorm - est correctement configuré, XDebug offre une aide inestimable pour déboguer un programme PHP.

Je vous propose ici une technique pour installer XDebug sous macOS Big Sur.

Note : au moment d'écrire ces lignes, AMPPS ne fonctionnait pas sous Big Sur. J'ai dû travailler avec XAMPP.

Je n'ai pas réussi à installer Xdebug avec la dernière version de XAMPP ( 7.4.1). J'obtenais le message « Xdebug requires Zend Engine API version 320180731. The Zend Engine API version 320190902 which is installed, is newer. ».

Tout a bien fonctionné une fois que j'ai installé une ancienne version de XAMPP (7.3.27-1).

▼Publicité Le texte se poursuit plus bas

PEAR (PHP Extension and Application Repository) et PECL (PHP Extension Community Library)

PEAR est un gestionnaire de paquets pour PHP.

PECL est son petit frère qui joue un rôle semblable sauf que ses extensions pour le PHP sont écrites en langage C et doivent être compilées.

Vous aurez besoin de PECL pour installer Xdebug.

L'installation de PEAR inclut l'installation de PECL.

Pour vérifier si PEAR est installé :

Terminal

pear version

Installer et configurer PEAR

Si vous obtenez le message « command not found », vous devez procéder à son installation :

Terminal

curl -O https://pear.php.net/go-pear.phar
sudo php -d detect_unicode=0 go-pear.phar

Vous obtiendrez un menu :

Résultat à l'écran

No log handling enabled - using stderr logging
Created directory: /var/db/net-snmp
Created directory: /var/db/net-snmp/mib_indexes

Below is a suggested file layout for your new PEAR installation. To
change individual locations, type the number in front of the
directory. Type 'all' to change all of them or simply press Enter to
accept these locations.

1. Installation base ($prefix) : /usr
2. Temporary directory for processing : /tmp/pear/install
3. Temporary directory for downloads : /tmp/pear/install
4. Binaries directory : /usr/bin
5. PHP code directory ($php_dir) : /usr/share/pear
6. Documentation directory : /usr/docs
7. Data directory : /usr/data
8. User-modifiable configuration files directory : /usr/cfg
9. Public Web Files directory : /usr/www
10. System manual pages directory : /usr/man
11. Tests directory : /usr/tests
12. Name of configuration file : /private/etc/pear.conf

1-12, 'all' or Enter to continue:

Je vous propose de modifier deux configurations :

Pour modifier le dossier de base de l'installation, entrez 1 suivi de Entrée.

Spécifiez le dossier /usr/local/pear

Pour modifier l'emplacement des fichiers compilés (binaries), entrez 4 suivi de Entrée.

Spécifiez le dossier /usr/local/bin

Note : vous pouvez à tout moment modifier ces configurations (voir ci-bas).

Configuer PEAR s'il est déjà installé

Si PEAR est déjà installé, vous devez vous assurer que ses configurations pointent vers des dossiers dans lesquels vous pourrez effectuer des modifications.

Si vous ne le faites pas et que vous tentez d'installer Xdebug, vous obtiendrez le message « Cannot install, php_dir for channel "pecl.php.net" is not writeable by the current user ».

Si le message vous invite à effectuer une mise à jour avec la commande pecl channel-update pecl.php.net, vous constaterez que cette commande génère elle aussi une erreur de droits : « Registry directory is not writeable by the current user » et ce, même si vous la faites précéder par sudo.

Si c'est votre cas, vous devez modifier certaines configurations.

D'abord, pour connaître les configurations :

Terminal

pear config-show

Pour modifier une configuration :

Syntaxe

pear config-set nom_configuration valeur

Vous devez modifier les configurations suivantes :

Terminal

pear config-set php_dir /usr/local/pear

pear config-set bin_dir /usr/local/bin
pear config-set cfg_dir /usr/local/pear/cfg
pear config-set data_dir /usr/local/pear/data
pear config-set doc_dir /usr/local/pear/docs

Xcode command-line tools

Pour réussir l'installation de Xdebug sous macOS Big Sur, vous aurez besoin des outils en ligne de commande de Xcode. C'est que l'installation régulière requiert des fichiers qui ne sont plus disponibles à l'endroit recherché et ce, depuis macOS Mojave.

Pour les installer, entrez cette commande dans une fenêtre Terminal :

Terminal

xcode-select --install

Si les outils en ligne de commande de Xcode sont installés, vous obtiendrez le message « command line tools are already installed ».

Sinon, une fenêtre vous demandera de lancer l'installation.

Cliquez sur Installer.

Installation de Xcode

Contourner le problème des fichiers non trouvés

Si vous tentez d'installer Xdebug à ce stade, vous obtiendrez le message  « fatal error: 'php.h' file not found ».

Pour contourner ce problème, vous devez d'abord connaître le chemin des fichiers recherchés, notamment php.h.

Terminal

sudo find /Library -name php.h

Vous obtiendrez un résultat semblable à celui-ci. Les versions dans les noms de fichiers pourraient différer. 

Résultat à l'écran

/Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk/usr/include/php/main/php.h
/Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include/php/main/php.h

Ces chemins sont très différents du /usr/include/php que les commandes phpize et php-config - requises pour l'installation - recherchent normalement.

La procédure fournie sur le blogue Affinity Bridge suggère de copier ces fichiers de commandes à un autre endroit et de modifier les versions copiées.

Terminal

cp /usr/bin/phpize /usr/local/bin/phpize
cp /usr/bin/php-config /usr/local/bin/php-config

Ouvrez le fichier /usr/local/bin/phpize à l'aide d'un éditeur, par exemple Geany.

Modifiez cette instruction, qui est environ à la ligne 8 :

Fichier /usr/local/bin/phpize

includedir="`eval echo ${prefix}/include`/php"

pour ceci, en prenant soin d'utiliser un des chemins trouvés plus tôt. Utilisez la version qui correspond à votre version de macOS ou celle qui s'en rapproche le plus  (ici : 11.1).

Fichier /usr/local/bin/phpize

includedir="`eval echo /Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk/usr/include`/php"

Ouvrez maintenant le fichier /usr/local/bin/php-config à l'aide d'un éditeur.

Modifiez ces instructions, qui sont environ aux lignes 9 et 13.

La seconde ligne doit être modifiée pour éviter le message d'erreur « ERROR: failed to write /usr/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so (copy(/usr/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so): failed to open stream: Operation not permitted) ».

Fichier /usr/local/bin/php-config

include_dir="${prefix}/include/php"
...
extension_dir='/usr/lib/php/extensions/no-debug-non-zts-20180731'

pour ceci, ici encore en prenant soin d'utiliser un des chemins trouvés plus tôt pour la première ligne.

Fichier /usr/local/bin/phpize

include_dir="/Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk/usr/include/php"
...
extension_dir='/usr/local/lib/php/extensions/no-debug-non-zts-20180731'

Installation de Xdebug

Maintenant que les outils requis sont installés et configurés, mettez à jour PECL :

Terminal

sudo pecl channel-update pecl.php.net

Lancez l'installation de Xdebug à l'aide de cette commande :

Terminal

sudo pecl install xdebug

À la fin du long processus, vous obtiendrez ceci à l'écran :

Résultat à l'écran

Build process completed successfully
Installing '/usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.0.3
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so" to php.ini  

Copier le fichier xdebug.so

Le fichier xdebug.so, dont le chemin a été surligné dans la sortie d'écran plus haut, doit être copié :

  • si vous travaillez avec AMPPS : dans le dossier /Applications/AMPPS/php-X.X/lib/extensions (ajustez le chemin selon votre version de PHP).
    Terminal

    cd /Applications/AMPPS/php-X.X/lib/extensions
    sudo cp /usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so .

  • si vous travaillez avec XAMPP : dans le dossier /Applications/XAMPP/xamppfiles/lib/php/extensions/no-debug-non-zts-20180731 (vérifiez avec phpinfo() le dossier exact de la configuration extension_dir).
    Terminal

    cd /Applications/XAMPP/xamppfiles/lib/php/extensions/no-debug-non-zts-20180731
    sudo cp /usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so .

Configurations dans php.ini

Il faut maintenant indiquer à php.ini où trouver le fichier xdebug.so.

Sous AMPPS, ouvrez ce fichier à l'aide du tableau de bord AMPPS.

Sous XAMPP, faites afficher une page Web avec l'instruction phpinfo(). Ceci vous indiquera le chemin exact du fichier php.ini à modifier.

Dans le fichier php.ini, vous devez vérifier la présence de l'instruction zend_extension = ".../xdebug.so".

Si elles est absente ajoutez-la près de la section Dynamic Extensions.

Vous devez spécifier le chemin du fichier xdebug.so.

Assurez-vous également que xdebug.remote_enable soit à 1.

Il ne doit pas y avoir de point-virgule devant ces instructions.

Fichier php.ini

;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;

zend_extension=xdebug.so
xdebug.remote_enable=1

Redémarrez votre serveur HTTP pour que les modifications soient prises en compte.

Relancez la page Web qui contient l'instruction phpinfo(). Vous devriez voir que Xdebug est activé et que xdebug.remote_enable est à On.

Si l'extension Xdebug n'apparaît pas dans la sortie de phpinfo(), consultez le fichier /Applications/XAMPP/xamppfiles/logs/error_log. Vous pourriez y trouver des indices sur ce qui n'a pas fonctionné.

Il vous reste désormais à configurer votre IDE, par exemple phpStorm, pour qu'il puisse faire appel au débogueur.

Pour écrire cet article, je me suis inspirée de ces sources :

« How to install Xdebug on macOS 11 Big Sur (Xcode 12) ». Profiling Viewer. https://profilingviewer.com/installing-xdebug-on-bigsur.html

« Adding php extensions to system php under os x 10.15 (Catalina) ». Affinity Bridge. https://affinitybridge.com/blog/adding-php-extensions-system-php-under-os-x-1015-catalina

« Installation of Xdebug on MacOS Catalina 10.15 ». Louis Charette. https://bbqsoftwares.com/blog/xdebug-catalina

Veuillez noter que le contenu de cette fiche vous est partagé à titre gracieux, au meilleur de mes connaissances et sans aucune garantie.
Dernière révision le 29 mars 2021
Merci de partager !

Site fièrement hébergé chez A2 Hosting.

Soumettre