Skip to Content
Wordpress / PHPPHP Debugging

Debugging PHP on MacOS with XDebug, Visual Studio Code and MAMP Pro

This is a tutorial on how to use Visual Studio Code, XDebug and MAMP Pro to debug PHP code live during runtime. Similar to Javascript and C# debugging, this combination gives PHP developers the ability to toggle break points and add “Watched Variables”’ to a monitored group, or to see variable changes live during program execution. It also removes the need to use print_r() or var_dump() as a means of determining timing, pattern changes, variable assignment and declaration.

Use Cases

  1. General PHP Custom Applications
  2. WordPress Custom Theme Development
  3. WordPress Plugin Development PHP Rest Services
  4. cURL Operations

Prerequisites

  1. Homebrew
  2. PHP
  3. Xdebug
  4. Visual Studio Code
  5. MAMP Pro
  6. PHP Debug Extension for Visual Studio Code

Optional

  1. PHP Server Extension for Visual Studio Code
  2. PHP IntelliSense Extension for Visual Studio Code

First Time Installation and Setup for all sites.

Homebrew, Xdebug & PHP (First time only, for all sites)

  1. Open Terminal
  2. Install Homebrew using Terminal/CLI.
sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. Install PHP using Terminal/CLI.
brew install php
  1. Install Xdebug with PECL using Terminal/CLI.
    • MacOS with ARM Silicon
sudo arch -arm64 sudo pecl install xdebug
  • MacOS with AMD Silicon
sudo arch -x86_64 sudo pecl install xdebug
  1. Verify that PHP is installed using Terminal/CLI.
php -v
  1. Locate php.ini and append Xdebug configuration.
php --ini
  1. Open the file listed as “Loaded Configuration File” in the output that was given to you by the previous command.
  2. Open php.ini in your favorite editor and append the following configuration to the bottom of the php.ini file. (It may already be there, but if not, or if you are confused, you can add it again and the bottom of the file and these lines will override any lines above it).
[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug

Install & Configure MAMP Pro (First time only, for all sites)

  1. Get license key from Integrity Team Password for MAMP Pro.
  2. Download MAMP Pro from here .
  3. Install MAMP Pro.
  4. Open MAMP Pro, and change the view to “Expert Mode” in the top left corner. screenshot-expert-mode.png
  5. In MAMP Pro, in the left navigation bar, click on “PHP” under “Languages”. Towards the top, you will see the version of PHP selected via a dropdown. Next to the dropdown you will see an “Open Template” button. Click this to open the php.ini file. (A warning will pop up, click “Open”.) We can edit this later here for next steps, or you can use a local file path.
  6. In MAMP Pro, in the left navigation bar, click on “PHP” if it’s not already open from the previous step. Towards the center of the PHP screen, find “Xdebug (Debugger)” and check the box next to it. Click the “Save” button and the PHP server will restart. screenshot-php-xdebug.png

Install & Configure Visual Studio Code (First time only, for all sites)

  1. Download & install Visual Studio Code from here .
  2. Install PHP Debug extension for VSCode. You can search the Extensions list for “PHP Debug” by “Xdebug” or click here  to go directly to the extension. screenshot-php-debug.png

VSCode + MAMP Pro Debugging for PHP Projects/Repos

General PHP Debugging

  1. Create directory for a new project OR clone existing Integrity PHP repo into a new project directory. (For WordPress specific projects, see below)
  2. Open MAMP Pro
  3. Under the “Hosts” tab, click the ”+” button to add a new host. You can use an existing repo such as a WordPress or PHP repo.
  4. Add a host “Name” which will be the URL for the site. (ex: integrity.local). Then select the “Document Root” which will be the path to the project’s repo directory. (ex: /Users/username/Sites/integrity). Click “Continue” to create the host.
  5. Open up MAMP Pro again, and click on the host you just added. Then next to its name, you will see an “Open” button which will open your site/app in your default browser at the host’s name on port 8888. Example: http://mamp-host-name:8888 .

WordPress PHP Debugging

Setting up existing WordPress repository

These instructions are for setting up a new host for MAMP using an existing WordPress site with a repository. You should only need a new local site. This should only be required for the initial setup of a local site.

  1. Clone an existing Integrity WordPress repo into a new project directory. (The repo should only consist of /wp-content plugins, theme files and other Integrity specific custom client files… not core WP files.)
  2. Open MAMP Pro
  3. On the mail screen, hit the ”+” button in the bottom left to create a new site. setup-repo-3.png
  4. On the next screen, click on the “WordPress” option under the “Basic” tab. setup-repo-4.png
  5. On the next screen, add your own “Name” to the site (you should match the name of the repo if possible) which will be your local domain name, then select the WordPress repository root from the first step. setup-repo-5.png
  6. Next, add a WordPress initial admin user credentials, and create an initial blank WordPress database. These credentials will be required to login to our initial dummy WordPress site using /wp-admin, then overwritten when we do a WordPress migration from staging/QA/Prod to our local machine. setup-repo-6.png
  7. Restart MAMP Server, then click on “Open” next to your new site. setup-repo-7.png
  8. From here, your browser will open the site at port 8888.

Setup VSCode to debug a MAMP Pro hosted site.

Once you have your new local MAMP site setup, use the following to set up VSCode to debug it. You should only have to do this once.

  1. Open VSCode
  2. Open the folder where you clone your repo and create the MAMP WordPress site in the previous steps.
  3. Click on the “Run and Debug” item in the left nav. Then click the “create a launch.json file” link. This will create the default options as a .json file for debugging with XDebug. setup-vscode-3.png
  4. This will open the center dropdown, select “PHP” from the options. setup-vscode-4.png
  5. This will automatically output the launch.json files into the root directory. The location of this file should be located at /(directory_root)/.vscode/launch.json. Take note of this incase you need to debug or make tweaks to the configuration later. setup-vscode-5.png
  6. Note: The default port that XDebug uses with MAMP Pro is 9000. Change this port number to 9000 in the launch.json if debugging does not initially hit breakpoints. setup-vscode-6.png

Start Debugging

Assuming you have all the previous steps setup and configured and you have added the “launch.json” .vscode file to your repo through VSCode, do the following to start your debugging session.

  1. Be sure you have the folder for your repo opened in VSCode.
  2. Click the “Run and Debug” nav item in VSCode
  3. Click the top “Play” button. (This should not be visible after we setup the launch.json file) debugging-3.png
  4. After clicking “Play,” return to your “Folder” listing or “Directory” listing in VSCode and select a PHP file. Click to the left of any line in the file to toggle breakpoint. You should also notice the “Step Through” controls are now visible at the top. debugging-4.png
  5. Refresh your site, and your breakpoint should turn from a “RED DOT” to a “RED DOT SURROUNDED BY A YELLOW PENTAGON”. You should also be able to view live variables in the “Run and Debug” tab. debugging-5.png

At this point, you should have a default site you can debug with Xdebug and VSCode.

Last updated on
Site SecurityPlugins