Forem: mouhssine nabil

How to Set Up Xdebug with Laravel Herd and PhpStorm on macOS

mouhssine nabil — Tue, 02 Dec 2025 21:54:04 +0000

A complete, step-by-step guide to configure Xdebug for debugging Laravel applications using Herd and PhpStorm.

Prerequisites
Understanding the Setup
Step 1: Configure Xdebug in Herd
Step 2: Configure PhpStorm
Step 3: Testing the Setup
Common Issues and Solutions
Tips and Best Practices

Prerequisites

macOS (Apple Silicon or Intel)
Laravel Herd installed and running
PhpStorm IDE
A Laravel project served by Herd
Basic knowledge of terminal commands

Understanding the Setup

Before diving in, it's important to understand how the components work together:

Xdebug: PHP extension that enables debugging
Herd: Manages PHP, Nginx, and serves your Laravel applications
PhpStorm: Listens for debugging connections from Xdebug
Browser Extension: Triggers Xdebug to activate for web requests

Key Concepts

PHP CLI vs PHP-FPM: Herd uses different PHP processes for command-line (CLI) and web requests (FPM)
Debug Socket: Herd has separate sockets for normal and debug modes
Port Configuration: Xdebug connects to PhpStorm on port 9003 by default

Step 1: Configure Xdebug in Herd

1.1 Identify Your PHP Version and Architecture

First, determine your PHP version and Mac architecture:

# Check PHP version
php -v

# Check architecture (arm64 = Apple Silicon, x86 = Intel)
uname -m

1.2 Configure the Debug Configuration File

Herd includes Xdebug extensions but requires configuration. Edit the debug configuration file:

# Open the debug.ini file for your PHP version
# Replace '83' with your PHP version (82, 81, etc.)
nano ~/Library/Application\ Support/Herd/config/php/83/debug/debug.ini

Add the following configuration:

# For Apple Silicon (M1/M2/M3)
zend_extension=/Applications/Herd.app/Contents/Resources/xdebug/xdebug-83-arm64.so

# For Intel Mac, use this instead:
# zend_extension=/Applications/Herd.app/Contents/Resources/xdebug/xdebug-83-x86.so

xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.start_upon_error=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

Important Notes:

Replace 83 with your PHP version (e.g., 82 for PHP 8.2)
Use arm64 for Apple Silicon or x86 for Intel
Use 127.0.0.1 instead of localhost to avoid DNS resolution issues

1.3 Optional: Configure the Main php.ini (for CLI debugging)

If you also want to debug CLI commands (artisan, tests):

# Open php.ini
nano ~/Library/Application\ Support/Herd/config/php/83/php.ini

Add the same Xdebug configuration as above.

1.4 Restart Herd

herd restart

After restarting, you should NOT see connection errors in the output. If you see errors, don't worry - they appear because PhpStorm isn't listening yet.

1.5 Verify Xdebug Installation

# Check if Xdebug is loaded
php -v
# You should see "with Xdebug v3.x.x"

# View Xdebug configuration
php --ri xdebug | grep -E "client_host|client_port|mode"

You should see:

xdebug.mode => debug,develop
xdebug.client_host => 127.0.0.1
xdebug.client_port => 9003

Step 2: Configure PhpStorm

2.1 Configure PHP Interpreter

Open PhpStorm
Go to Settings/Preferences (Cmd + ,)
Navigate to PHP
Next to CLI Interpreter, click the three dots (...)
Click the + button
Select Other Local...

Browse to Herd's PHP binary:
(Or let PhpStorm auto-detect it)

/Users/[your-username]/Library/Application Support/Herd/bin/php83

Verify that PhpStorm shows:
- PHP version: 8.3.x
- Xdebug: 3.3.x ✓
Click OK

2.2 Configure Server

This is crucial and often the source of problems.

In Settings, go to PHP → Servers
Click + to add a new server
Configure:
- Name: your-domain.test (e.g., myapp.test)
- Host: your-domain.test (same as name)
- Port: 443 (if using HTTPS) or 80 (if using HTTP)
- Debugger: Xdebug
- ☐ Use path mappings: Leave UNCHECKED

Critical: Port Configuration

If your Herd site uses HTTPS (most do by default), use port 443
If using HTTP, use port 80
To check: look at your browser URL - https:// = port 443, http:// = port 80
Click Apply

Pro Tip: If you're unsure about the port, delete the server configuration and PhpStorm will auto-detect it on the first connection and suggest the correct port (usually 443).

2.3 Configure Debug Settings

Go to PHP → Debug
In the Xdebug section, verify:
- Debug port: 9003
- ☑ Can accept external connections: Can be checked
- ☐ Force break at first line when no path mapping specified: UNCHECKED
- ☐ Force break at first line when a script is outside the project: UNCHECKED

These last two options prevent PhpStorm from stopping at Herd's internal files.

Click OK

2.4 Start Listening for Debug Connections

In the PhpStorm toolbar (top right), find the phone icon (📞) and click it to activate "Start Listening for PHP Debug Connections".

The icon should turn green when active.

Alternative: Go to Run → Start Listening for PHP Debug Connections

Step 3: Testing the Setup

3.1 CLI Debugging (Quick Test)

Create a simple test file:

<?php
// test-xdebug.php

echo "Starting Xdebug test...\n";

$name = "Developer";  // ← Place breakpoint here
$message = "Hello " . $name;

echo $message . "\n";
echo "Test finished.\n";

Place a breakpoint on the line $name = "Developer"; (click in the left margin)
Save the file (Cmd + S)
Ensure PhpStorm is listening (green phone icon)
Run from terminal:

php test-xdebug.php

Expected Result:

Terminal pauses
PhpStorm comes to the foreground
The breakpoint line is highlighted in blue
Variables panel shows values

If this works, Xdebug is configured correctly! ✓

3.2 Web Debugging

For debugging web requests, you need to trigger Xdebug from the browser.

Option A: Browser Extension (Recommended)

Install Xdebug Helper:
- Chrome: Xdebug Helper
- Firefox: Xdebug Helper
Configure the extension:
- Click the extension icon
- Go to Options/Settings
- Set IDE Key to PHPSTORM
- Save
Activate debugging:
- Click the extension icon
- Select Debug (icon turns green)

Option B: URL Parameter

Add this to your URL:

https://your-domain.test/your-route?XDEBUG_SESSION_START=PHPSTORM

3.3 Debug a Laravel Route

Open routes/web.php
Place a breakpoint inside a route:

Route::get('/test-debug', function () {
    $data = "Testing Xdebug";  // ← Breakpoint here
    return view('welcome', compact('data'));
});

Save the file (Cmd + S)
PhpStorm is listening (green icon)
Browser extension is active (green)
Visit the route: https://your-domain.test/test-debug

Expected Result:

Browser page starts loading but pauses
PhpStorm comes to foreground
Breakpoint line is highlighted
You can inspect all variables: $data, $request, etc.
Use controls: Resume (F9), Step Over (F8), Step Into (F7)

Common Issues and Solutions

Issue 1: "Could not connect to debugging client" Errors

Symptoms: Errors appear when running herd restart

Cause: Xdebug tries to connect but PhpStorm isn't listening yet

Solution: These errors during Herd startup are normal and harmless. They only matter if they appear when actually trying to debug.

Issue 2: CLI Debugging Works, Web Debugging Doesn't

Symptoms: Breakpoints work with php artisan or terminal commands, but not from browser

Root Causes:

Wrong port in PhpStorm server configuration (most common)
PHP-FPM not loading Xdebug
Browser extension not configured properly

Solutions:

A. Fix Server Port Configuration

If using HTTPS (default for Herd), set port to 443
If using HTTP, set port to 80
To auto-detect: Delete the server in PhpStorm, then debug from browser - PhpStorm will suggest the correct configuration

B. Verify PHP-FPM Loads Xdebug

Create public/info.php:

<?php phpinfo();

Visit https://your-domain.test/info.php and search for "xdebug".

If you DON'T see an Xdebug section, PHP-FPM isn't loading it. Verify the debug.ini file path and restart Herd.

C. Check Browser Extension

Verify the extension is set to PHPSTORM (not YOUR-NAME or other values)
Check cookies: Open DevTools → Application → Cookies
You should see XDEBUG_SESSION=PHPSTORM

Issue 3: PhpStorm Doesn't Stop at Breakpoints

Symptoms: Everything seems configured, but PhpStorm doesn't react

Solutions:

A. Verify PhpStorm is Actually Listening

lsof -i :9003

You should see PhpStorm listening on port 9003. If not, restart PhpStorm.

B. Check Debug Settings

Settings → PHP → Debug
Verify "Ignore external connections through unregistered server configurations" is UNCHECKED

C. Accept First Connection

The first time Xdebug connects, PhpStorm shows a popup: "Incoming connection from Xdebug"
Click Accept
This popup might be hidden behind other windows - check!

D. Enable Xdebug Logging

Add to debug.ini:

xdebug.log=/tmp/xdebug.log

Restart Herd, then check the log:

tail -f /tmp/xdebug.log

Issue 4: Breakpoint Stops at Herd's Internal Files

Symptoms: Debugger stops at files like dump-loader.php instead of your code

Solution:

Settings → PHP → Debug
Uncheck: "Force break at first line when no path mapping specified"
Uncheck: "Force break at first line when a script is outside the project"

Issue 5: Using `localhost` Instead of IP

Symptoms: Connection errors even though everything is configured

Solution: Always use 127.0.0.1 instead of localhost in the Xdebug configuration. macOS can have DNS resolution issues with localhost.

Tips and Best Practices

1. Debugging Artisan Commands

Use Herd's debug command:

herd debug artisan your:command

Or set environment variable:

XDEBUG_CONFIG="idekey=PHPSTORM" php artisan your:command

2. Debugging PHPUnit Tests

herd debug vendor/bin/phpunit

Or in PhpStorm, create a PHPUnit run configuration with the Herd PHP interpreter.

3. Conditional Breakpoints

Right-click a breakpoint → Add condition:

$user->id == 123

PhpStorm will only stop when the condition is true.

4. Evaluate Expressions

While debugging, select any expression in your code, right-click → Evaluate Expression (or press Alt + F8).

5. Quick Debugging Toggle

Create a keyboard shortcut for "Toggle Line Breakpoint":

Settings → Keymap → Search for "Toggle Line Breakpoint"
Set to Cmd + F8 for quick breakpoint toggling

6. Xdebug Performance Impact

Disable Xdebug when not needed to maintain performance:

# Comment out the zend_extension line in debug.ini
# Or use Herd Pro's auto-detection feature

With Herd Pro, Xdebug only activates when breakpoints are detected, keeping your app fast.

7. Multiple Projects

If working on multiple projects:

Each project can have different server configurations in PhpStorm
The server name should match the domain: project1.test, project2.test, etc.

8. Remote Debugging (Optional)

If debugging from a different machine:

In debug.ini:

xdebug.client_host=192.168.x.x  # IP of machine running PhpStorm

Also configure your firewall to allow connections on port 9003.

Troubleshooting Checklist

When debugging doesn't work, verify ALL of these:

Herd Configuration:

[ ] debug.ini exists and contains correct configuration
[ ] Correct architecture (arm64/x86) specified
[ ] xdebug.client_host=127.0.0.1 (not localhost)
[ ] xdebug.client_port=9003
[ ] Herd restarted after config changes

PhpStorm Configuration:

[ ] PHP interpreter shows Xdebug loaded
[ ] Server name matches domain
[ ] Server port is correct (443 for HTTPS, 80 for HTTP)
[ ] Path mappings are disabled (unchecked)
[ ] Debug port is 9003
[ ] Force break options are unchecked
[ ] PhpStorm is listening (green phone icon)

Browser/Testing:

[ ] Browser extension installed and configured
[ ] Extension IDE key is "PHPSTORM"
[ ] Extension is activated (green icon)
[ ] Breakpoint is placed and file is saved
[ ] Cookie XDEBUG_SESSION=PHPSTORM exists

Verification:

[ ] php -v shows Xdebug loaded
[ ] lsof -i :9003 shows PhpStorm listening
[ ] phpinfo() from browser shows Xdebug section
[ ] CLI debugging works (php test-file.php)

Conclusion

Setting up Xdebug with Laravel Herd and PhpStorm involves configuring three main components:

Xdebug (via Herd's debug.ini)
PhpStorm (interpreter, server, debug settings)
Trigger mechanism (browser extension or URL parameter)

The most common pitfall is the server port configuration - always verify you're using the correct port (443 for HTTPS, 80 for HTTP).

Once configured correctly, you'll have a powerful debugging environment that works seamlessly for both CLI and web debugging.

Happy debugging! 🐛✨

Additional Resources

Tested With: Laravel Herd 1.x, PhpStorm 2024.x, PHP 8.3, macOS Sonoma

*More tips find me on *: cherradiX.dev

How to install (Ubuntu 22.10 VM) vagrant on Mac M1 ship using QEMU

mouhssine nabil — Thu, 21 Mar 2024 18:20:01 +0000

How to Ubuntu 22.10 (Kinetic Kudu) arm64 (Tested on macbook pro 2020 M1)

In this blog post, I will show you how to install and run vagrant on an M1 Mac using QEMU as the virtualization provider. Vagrant is a tool that simplifies the creation and management of virtual machines for development and testing purposes. QEMU is an open source emulator that can run various architectures, including arm64, which is the native architecture of the M1 chip.

Before we begin, make sure you have Homebrew installed on your Mac. Homebrew is a package manager that makes it easy to install software and dependencies. You can install Homebrew by following the instructions on their website: https://brew.sh/

Install QEMU

QEMU is the software that will emulate the arm64 architecture and run the virtual machine. To install QEMU, open a terminal and run the following command:

brew install qemu

Find info about image here https://app.vagrantup.com/perk/boxes/ubuntu-22.10-arm64

Install vagrant-qemu plugin

vagrant plugin install vagrant-qemu

Init Vagrantfile

vagrant init -m perk/ubuntu-22.10-arm64

This will generate a minimal Vagrantfile that uses the perk/ubuntu-22.10-arm64 box as the base image. A box is a pre-packaged virtual machine image that contains an operating system and some software. The perk/ubuntu-22.10-arm64 box is an arm64 version of Ubuntu 22.10 (Kinetic Kudu), which is compatible with the M1 chip.

Alternatively, you can write your own Vagrantfile with more options and customizations. For example, you can add a line to forward a port from the guest to the host machine, like this:

Or edit vagrant file like the following

Vagrant.configure("2") do |config|  config.vm.network :forwarded_port, guest: 86, host: 1990  config.vm.box = "perk/ubuntu-22.10-arm64"end

Run vagrant

This will download the box image if it is not already cached, create a new virtual machine based on the Vagrantfile, and boot it up using QEMU as the provider. You should see something like this:

vagrant up --provider qemu# orvagrant up

SSH your OS

Once the virtual machine is up and running, you can access it via SSH by running:

vagrant ssh

This will log you in as the vagrant user, which has sudo privileges and can run commands as root. You should see something like this:

Welcome to Ubuntu 22.10 (GNU/Linux 5.13.0-20-generic aarch64)

* Documentation: <https://help.ubuntu.com>
* Management: <https://landscape.canonical.com>
* Support: <https://ubuntu.com/advantage>

System information as of Fri Jun 9 20:54:10 UTC 2023

System load: 0.0 Processes: 103
Usage of /: 3.6% of 38.71GB Users logged in: 0
Memory usage: 7% IPv4 address for eth0: 10.0.2.15
Swap usage: 0%

* Super-optimized for your M1 Mac!

* Canonical Livepatch is available for installation.
- Reduce system reboots and improve kernel security. Activate at:
<https://ubuntu.com/livepatch>

0 updates can be installed immediately.
0 of these updates are security updates.

The list of available updates is more than a week old.
To check for new updates run: sudo apt update

*** System restart required ***
Last login: Fri Jun 9 20:54:10 2023 from 10.0.2.2
vagrant@ubuntu-22-10-arm64:~$

👍 Now you can run any commands or install any software you want on the virtual machine, just like you would on a regular Ubuntu system.