XDEBUG_SESSION_START
By default, even after installing the Xdebug extension, you have to take further action to start a remote debugging session. This is typically done by appending a query string parameter called XDEBUG_SESSION_START to the URL. As an alternative, you can also send XDEBUG_SESSION_START with POST data. Both methods create a special cookie in your browser that instructs Xdebug to start a remote debugging session automatically, so you do not have to include the XDEBUG_SESSION_START parameter on subsequent requests. That cookie is typically valid for one hour, but the maximum age is controlled by the xdebug.remote_cookie_expire_time setting, which can be changed in the php.ini config file.
Browser Extensions
One way to simplify the process of starting a remote debugging session is to use a special browser extension such as Xdebug helper for Chrome. Such extensions place the XDEBUG_SESSION cookie in your browser and they typically make it valid for much longer than an hour. They also allow you to add or remove the cookie with a push of a button. Similar extensions are available for all major browsers.
Limitations
While all of the above methods of starting a remote debugging session are valid, they are not without limitations.
If you are developing a single-page application and your frontend and backend are hosted on different domains, setting the Xdebug cookie using an extension may not do you much good, because the extension will set the cookie on the frontend domain instead of the backend domain where you actually need it.
As another example, if you are building an API, and especially a REST API, it may not be practical to send the Xdebug cookie with all requests, but it may not necessarily be any more convenient to add the XDEBUG_SESSION_START parameter to individual requests. If your API is consumed by an Android or iOS app, having to recompile the app is just too time-consuming.
remote_autostart
Luckily, there is a better way of starting a remote debugging session. Xdebug comes with a very powerful feature called remote autostart. To enable it, add the following line to your php.ini config file:
xdebug.remote_autostart = 1
Once you have done so, Xdebug will attempt to start a remote debugging session automatically on every request without a need for special URL parameters, POST data, or cookies. As an added bonus, remote_autostart also works automatically with CLI scripts.
Tips for PhpStorm Users
If you are a PhpStorm user, I recommend that you assign a shortcut to the “Listen for debugger connections” setting in PhpStorm as that shortcut will most likely become your replacement for all Xdebug browser extensions. And while you are adjusting PhpStorm settings, take a look at the “Break at first line in PHP scripts” feature and consider disabling it to save yourself the trouble of having to resume every remote debugging session. Simply relying on breakpoints set in the code will allow you to keep the “Listen for debugger connections” setting on for long periods of time.
Conclusion
For me, the most important advantage of remote_autostart over other methods is that it increases my productivity. I never have to manually edit any URLs or install browser extensions, regardless of whether I am debugging a legacy website or a brand new single-page application. I am sure that once you become accustomed to remote_autostart, you will wonder how you ever debugged PHP code without it.
Do you have a topic you’d like us to cover? Email your suggestion to suggest@sourcetoad.com.
