How to step debug a queued job

For those times when dd is not enough

Joel Clermont
Joel Clermont
2024-03-20

A lot of Laravel developers use dd to figure out why their code isn't working as expected. I do it too. It's very handy!

But occasionally, there are scenarios where dd isn't the most productive way to unravel a thorny problem. In those cases, a more powerful tool like Xdebug can be very useful in walking through a request line by line.

Xdebug makes it easy to debug a web request. You add a query string or toggle a browser extension, and the debugger will start a session.

But what if the thing you're trying to debug is a queued job? How can you trigger the debugger to start when the job is picked up by the worker?

There are other ways to trigger an Xdebug session besides a request variable or a cookie (set by the browser extension). You can also do it by setting an environment variable.

So instead of calling php artisan queue:work, you can call XDEBUG_SESSION=1 php artisan queue:work. This will signal to your editor that it should start a debugging session when the worker picks up a job.

The same approach works if you're using Horizon too.

Hope this helps,

Joel

P.S. I gave a talk at the Laravel Worldwide Meetup about why Xdebug is a useful tool even if we normally use dd. Give it a watch!

Toss a coin in the jar if you found this helpful.
Want a tip like this in your inbox every weekday? Sign up below 👇🏼

Level up your Laravel skills!

Each 2-minute email has real-world advice you can use.