Skip to content

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#

  1. Install Homebrew

In the terminal enter the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  1. Install PHP through Homebrew.

    Following command will get you the most recent PHP version: 

    brew install php

  2. Install Xdebug with PECL

This command will install latest Xdebug:

pecl install xdebug
  1. 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.

  1. Locate php.ini and append Xdebug configuration:

Run the following command to find the location of php.ini file 

php --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.

  1. (Optional) You can turn xdebug.start_with_request=yes (in Xdebug 2 it was xdebug.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 has XDEBUG_SESSION_START query parameter, which might complicate scenarios like debugging AJAX requests.

See Also#