Skip to content

How to Configure PHP Debugging in MAMP with Visual Studio Code on macOS

Setting up a reliable PHP debugging environment is crucial for efficient web development. In this guide, I’ll walk you through the process of configuring Xdebug with MAMP and Visual Studio Code (VS Code) on macOS. By the end of this tutorial, you’ll be able to debug your PHP code seamlessly, setting breakpoints, inspecting variables, and controlling the execution flow directly from VS Code.

Installing and Verifying PHP 8.2 in MAMP

Before diving into the Xdebug configuration, make sure you have PHP 8.2 installed and active in MAMP:

  • Set PHP Version in MAMP: open MAMP, go to Preferences > PHP, and select PHP 8.2.x from the dropdown menu.
  • Verify PHP Version: open the terminal and run:
    /Applications/MAMP/bin/php/php8.2.x/bin/php -v
    This should return the PHP 8.2.x version information, confirming that PHP is set up correctly.

Installing Xdebug for PHP 8.2

Xdebug is a powerful debugging tool for PHP. If it’s not already installed with MAMP, you can follow these steps:

  • Download Xdebug: go to the Xdebug Downloads page and find the correct version for PHP 8.2.x by providing your PHP configuration details, or check them using php -i in the terminal.
  • Install the Xdebug Extension: after downloading the correct .so file, move it to the appropriate directory:
    sudo mv xdebug.so /Applications/MAMP/bin/php/php8.2.x/lib/php/extensions/no-debug-non-zts-xxxxxxx/
    Ensure that the paths match your installation.

Configuring Xdebug in PHP

Next, you’ll need to configure Xdebug in your php.ini file:

  • Edit php.ini: open the php.ini file located in /Applications/MAMP/bin/php/php8.2.x/conf/php.ini
  • Add the following configuration at the end of the file:
    [xdebug]
    zend_extension="/Applications/MAMP/bin/php/php8.2.x/lib/php/extensions/no-debug-non-zts-xxxxxxx/xdebug.so"
    xdebug.mode=debug
    xdebug.start_with_request=yes
    xdebug.client_host=127.0.0.1
    xdebug.client_port=9003
    xdebug.log=/Applications/MAMP/logs/xdebug.log
  • Restart MAMP: after saving the changes, restart MAMP to apply the new configuration.
  • Verify Xdebug Installation: run the following command in the terminal to ensure Xdebug is loaded
    /Applications/MAMP/bin/php/php8.2.x/bin/php -m | grep xdebug
    You should see “xdebug” listed, confirming that the extension is active.

Setting Up VS Code for PHP Debugging

Now that Xdebug is set up, you need to configure Visual Studio Code to listen for debugging connections from Xdebug.

  • Install the PHP Debug Extension: in VS Code, go to the Extensions view (click on the square icon in the sidebar or press Cmd+Shift+X) and search for “PHP Debug” and install it.
  • Create and Configure launch.json: open your PHP project in VS Code and go to the Debug view (click on the bug icon or press Ctrl+Shift+D). Click on the gear icon to create a launch.json file and add the following configuration:
    {
    "version": "0.2.0",
    "configurations": [{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": { "/Applications/MAMP/htdocs/projectName": "${workspaceFolder}" }
    }]
    }
    Ensure that ${workspaceFolder} points to your project’s root directory.

Testing the Debugging Setup

To ensure everything is working correctly:

  • Set Breakpoints: open a PHP file in your project and click to the left of the line number to set a breakpoint (a red dot will appear).
  • Start Debugging: click the green “Start Debugging” button in the Debug view.
    In your browser, navigate to the page you want to debug (e.g., http://localhost:8888/your_project/index.php).
  • Inspect the Debugging Session: if everything is set up correctly, the execution will pause at your breakpoint in VS Code, and you’ll be able to inspect variables, step through the code, and more.

Troubleshooting Common Issues

  • Breakpoints are disabled: ensure that pathMappings in launch.json correctly maps the local project directory to the server directory.
  • Xdebug not detected: double-check the php.ini configuration and ensure the correct version of Xdebug is installed.
  • Port conflicts: make sure that no other service is using the port 9003.

Conclusion

With Xdebug configured in MAMP and VS Code, you now have a powerful setup for PHP development on macOS.
This setup allows you to debug your PHP code effectively, enhancing your development process and helping you quickly identify and fix issues. Happy coding!