Xdebug on Mac
To debug PHP applications with PHP Tools for Visual Studio Code, it is necessary to install and enable Xdebug extension.
There are multiple ways how to install Xdebug on macOS:
- Compile it from the source code. We have prepared a detailed step-by-step tutorial on how to do that. Please continue here
- Use PECL and Homebrew. The rest of the document will explain this approach.
Step-by-step guide
-
Install Homebrew
In the terminal enter the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
Install PHP through Homebrew.
Following command will get you the most recent PHP version:
brew install php
-
Install Xdebug with PECL
Choose which command to run depending on your Mac architecture:
-
Intel
pecl install xdebug
-
Apple M1
arch -arm64 sudo pecl install xdebug
or if PHP was compiled for x86_64 architecture, then run this command:
arch -x86_64 sudo pecl install xdebug
-
-
Verify the installation
php -v
You should see output like this:
PHP 8.0.17 (cli) (built: Mar 18 2022 09:45:09) (NTS) Copyright (c) The PHP Group Zend Engine v4.0.17, Copyright (c) Zend Technologies with Xdebug v3.1.3, Copyright (c) 2002-2022, by Derick Rethans with Zend OPcache v8.0.17, Copyright (c), by Zend Technologies
If the output contains Xdebug - the PECL updated your
php.ini
then you are done. If not, continue with Step 5. -
Locate
php.ini
and append Xdebug configuration:Run the following command to find the location of
php.ini
filephp --ini
The output should look similar to this:
Configuration File (php.ini) Path: /opt/homebrew/etc/php/8.0 Loaded Configuration File: /opt/homebrew/etc/php/8.0/php.ini Scan for additional .ini files in: /opt/homebrew/etc/php/8.0/conf.d Additional .ini files parsed: /opt/homebrew/etc/php/8.0/conf.d/error_log.ini, /opt/homebrew/etc/php/8.0/conf.d/ext-opcache.ini, /opt/homebrew/etc/php/8.0/conf.d/php-memory-limits.ini
Open
/opt/homebrew/etc/php/8.0/php.ini
file and append the following lines(if not already present):zend_extension="xdebug.so" xdebug.mode=debug
save and verify the installation again by running
php -v
command. -
(Optional) You can turn
xdebug.start_with_request=yes
(in Xdebug 2 it wasxdebug.remote_autostart=1
). This option will activate the debugger on each request. By default, Xdebug initiates the debug session only when it's instructed to, e.g. when the URL hasXDEBUG_SESSION_START
query parameter, which might complicate scenarios like debugging AJAX requests.See Also