Xdebug On Demand for CLI PHP Scripts in PhpStorm 2016.2

You may have noticed recent versions of the Composer dependency manager has come with a warning if you have Xdebug enabled:

Composer Warning

Jordi added this warning because Xdebug does wondrous things when you are developing, but it slows down execution of PHP scripts massively. Turning Xdebug on and off depending on the situation can be a painful chore… Until now.

PhpStorm 2016.2 introduces Xdebug On Demand mode where you can disable Xdebug for your global PHP install, and PhpStorm will only enable it when it needs to — when you’re debugging your scripts, or when you need code coverage reports.

To use the great new feature, first, you need to disable Xdebug for command line PHP scripts. Usually, this is a case of either renaming a config file, or commenting out the lines that load the extension. While you’re working with the configuration that enables Xdebug in your actual PHP install, it’s worth taking a note of where the Xdebug extension lives on your system as you’ll need that later.

What you are looking for is when you run php -v from the command line, you don’t get the “with Xdebug by Derick Rethans” line:

php -v result

Now we don’t have Xdebug installed, and our command line scripts (including Composer and our unit tests) will run much faster.

Next, we need to tell PhpStorm where to find Xdebug when we need it. To do this, navigate to Languages and Frameworks and then PHP in the preference pane. You’ll see a list of your configured interpreters in a drop down, pick the relevant PHP install and then press the  button to see it’s settings:

Xdebug Settings

We just need to tell PhpStorm where to find the Xdebug extension in the Debugger extension field – that’s the location you should have taken note of earlier when you were looking at the config files. When you opened this screen, the Debugger information to the right of the PHP version said Not installed, but once you’ve set the debugger location, hitting the refresh icon above it will confirm that the extension is found and can be loaded; it will change to the version of Xdebug you are running.

Now we can debug as usual. If it’s a simple PHP script, then either use the Debug toolbar icon to start a debugging session (as usual), or if you don’t have a run configuration, right-click anywhere in the file, and select Debug and then the file name with the PHP file icon next to it. This will allow you to start a debug session right there without even running the debug session listener.

If you want to debug your PHP Unit tests, assuming you have a PHP Unit runner configured and you can debug your unit tests in the same way; by selecting the PHP Unit configuration from the drop-down in the menu bar, and then hitting the Debug button.

Making debugging easier and quicker is a definite goal in recent releases of PhpStorm, and personally, I think this solves a very annoying problem and speeds up execution of tests and other command-line scripts in the 90% use case; when you don’t need to debug or profile.

I hope you are excited as I am with this feature, give it a go and let me know what you think!

— Gary and the PhpStorm Team

About Gary Hockin

Gary Hockin has been creating code to power web applications for 15 years, the last three of them at an extraordinary level. He is handsome, talented, funny and articulate, and also extremely modest. Gary is a valued contributor to Zend Framework 2 and is a member of the community review team. He's married and has two wonderful children, and when he's not coding, writing about code, speaking about code or reading about code, he can usually be found in the pub playing pool.
This entry was posted in Cool Feature and tagged . Bookmark the permalink.
  • Markus Wolff

    Thank you!!!!! Finally no more jumping through hoops :-)

  • Samuel Hughes Mensah

    it is possible to compile PHP to .txt t just like as Jade is to HTML using file watchers in the IDE. PHP can be used as a templating engine to preprocess PHP to any text. i have posted this question to stack overflow and site point but no lack.
    May be my approach to the question is wrong but Jetbrain Users might understand me better. To anyone who would spent a minute looking at the question, i say Thank U.


  • Jacques Marques

    This feature works with PHP 5.6 or only with PHP 7?

  • https://ksdev.pl ksdev

    Can we use it to debug full web application (for example using laravel framework)? If yes, how?

    • Piotr Czyz

      It is a very good question. Does anyone know answer?

  • Ryan M

    Hi, this is a nice feature to see. I’ve set it up, and can debug individual files. However, my app runs as a front-end ‘request’ (which then includes hundreds of files). Enabling ‘Start Listening for PHP Debug Connections’ is now not enough since xdebug is not included normally. Any approach to ‘on demand’ that has a standard workflow (not a specific ‘debug’ configuration through PHPStorm)? Thanks!

    • Marcel Hernandez

      Have a dedicated php.ini configuration file for the command line interpreter and another one for the webserver. This way you can leave xdebug enabled by default in the latter, and do what this article recommends in the former, which is the one that PHPStorm will use.

      ├── apache2
      │ ├── php.ini
      │ └── …
      └── cli
      ├── php.ini
      └── …

      BTW this is the standard PHP setup on some (most?) Linux distros such as Debian/Ubuntu.

      • Ryan M

        Hi Marcel, thanks. My concern is over performance for the webserver, for my needs I don’t care about CLI PHP performance. Is it possible to do ‘on demand’ XDebug with PHPStorm? It seems that there is still the old ways of doing it – adding a GET request variable to the header, or leaving XDebug on all the time for the webserver-based development. Thanks for your response!

  • Matias Iglesias

    Doesn’t work for me…. Running apache on localhost. I’ve already set breakpoints, debug project and nothing happens…. Any hint?

  • Михаил Красильников

    Doesn’t work with PHPUnit.

  • Ivan Zvonimir Horvat

    CLI debug doesn’t work, in some cases it skips breakpoints “Resume Breakpoints”, while on regular cli+debug works fine always

  • Christian

    The new Debuger is not working. Still have to use the old way.
    Using the Debug-Icon is running CLI.Script without parameters and I need to define some params. The Debug-Listener alone is not enough.

  • http://www.samboush.com/ Michal Samboush Vojtíšek

    After upgrade to 2016.2 PhpStorm stop working with XDebug on local Apache. Now I can debug single file in PHPStorm. But not whole App like before.

  • phan7om

    How to enable this XDEBUG feature for remote debugging with PHPSTORM cookie for php-fpm configuration?