Installing xdebug3 for PHP8 for mac users (PHPStorm + Laravel)

The Problem

I’ve tried to install xdebug on my mac recently, the installation part went smoothly and i followed few instructions that i found online, but neither of them worked, it seemed to me that something is off, and i was right.

Since the release of xdebug3, few configurations that is related to xdebug.remote_enable.* and few more is renamed. you can read more of it here.

Here i will go through all the details for installing xdebug and configuring it on PhpStorm to debug your Laravel (or any other PHP) application.

Installation

It seems homebrew has removed xdebug flavor of PHP, but fear not, the installation is quite simple, i assume you have installed PHP already if not, you can use homebrew to do that:

brew install php

Now we will install xdebug:

pecl install xdebug

That’s all, you should have xdebug installed, verify it using:

php -m | grep xdebug

But here’s the tricky part, it’s installed but the configurations are not correct to be used in PHPStorm, first lets find your php.ini :

php --ini | grep "Loaded Configuration File"

Now open it with your editor of choice and add these lines below zend_extension=”xdebug.so”:

xdebug.mode=debug
xdebug.start_with_request=yes

Note: previously you had to add xdebug.remote_enable and few more like it but it’s have been replaced in xdebug3 with the ones you just added.

If you’re using valet to develop your applications locally, you have to restart it to enable xdebug:

valet restart

now write phpinfo() in a route of your application and verify xdebug configurations.

That’s all! you should have xdebug3 ready to be used in your IDE.

Setting it up in PHPStorm

Now that xdebug is up and running, all you have to do is to create a configuration for debugging your application. before you do this, make sure right PHP version and interpreter is selected:

Go to Preferences > PHP, and make sure PHP 8.1 is selected and CLI Interpreter is set to 8.1.2 (or whatever version your PHP installation is). if you don’t see it, click on … button right in front of CLI Interpreter field and add a new one.

If you need to find your PHP executable path, run which php in your terminal and copy the path. (once entered you should be able to see xdebug version).

Now go to Run > Edit Configurations… and add a new “PHP Built-in Web Server”, make sure you add public to your Document Root, choose a Host and port. then click OK.

That’s all, and a breakpoint somewhere, to Run > Debug, hit the endpoint which executes the breakpoint.

Enjoy debugging!