How to debug PHP applications¶
This guide covers three ways to debug PHP applications:
- Debugging from within Homestead
- Debugging by viewing a PHP object in Chrome
- Debugging on a local machine (i.e. not in Homestead)
Debugging in Homestead¶
Following instructions explain how to install, setup and configure Xdebug in Homestead box and work with PhpStorm IDE. This page contains a more comprehensive set of instructions.
Install the Xdebug on Homestead by first logging in as super user.
sudo apt-get install php-xdebug
/etc/php/your_php_version/fpm/conf.d/20-xdebug.ini in a text editor and configure
xdebug.ini with the following settings:
zend_extension = xdebug.so xdebug.remote_enable = 1 xdebug.remote_connect_back = 1 xdebug.remote_port = 9000 xdebug.max_nesting_level = 512
Do the same with
If it does not exist, enable the
xdebug module with:
sudo phpenmod xdebug
To confirm that Xdebug was set up correctly, run:
to list all your installed PHP modules, and look for
In PHPStorm, navigate to Settings->PHP->Servers (Settings may be called Preferences in MacOS) and find your project files.
In the Absolute path on the server, enter the path where your project is saved in your Homestead environment.
You should also make sure that PHPStorm is connected to PHPUnit by selecting Run > Start Listening for PHP Debug Connections.
Now you are set up, you can set a breakpoint in the PHP script and refresh the page in the browser you want to debug.
Viewing PHP objects in Chrome / Firefox¶
To view a live PHP object from your browser:
- Download Debugging.php and add the class to your project.
- Call the
phpObjectToChrome()function and pass in the appropriate arguments (see below).
- Open the dev tool in the browser (Ctrl+Shift+I in Chrome) and the PHP object should be there.
Arguments to phpObjectToChrome()¶
$object: This is the object that will be sent to the browser console and is passed via the function parameters.
- String -
$objectName: This is a string that will be used as a label for the object in the console.
- global static array:
$fullTraces: this is a static array that will store all the values of all
debug_backtracefor all the calls that are made to the
- Store the backtrace in
- Convert the PHP object (
$object) to an array using the PHP
- Use the
getShortInfo()function to check for and get values from the backtrace. Return array with the different values. After this information is returned, extract certain elements such as class and store them in individual variables, for example, the class would be stored in the
console.log()to return the short information for this call. This includes values such as the class name, file name etc.
console.log()the JSON version of the
- Convert the current array of
Debugging on your local machine (i.e. without Homestead)¶
The following sections describe how to install and configure Xdebug for a specific operating system.
- Go to this page and download the correct 32/64 bit version. Do not get the non-TS version.
- In your
php.inifile (find it where you installed PHP), under 'Module Settings', add the following:
[Xdebug] zend_extension="path to .dll file you downloaded in step 1" xdebug.remote_enable=1 xdebug.remote_host=localhost xdebug.remote_port=9000 xdebug.remote_handler=dbgp
Under 'Dynamic Extensions' add
MacOS High Sierra¶
MacOS High Sierra comes with a pre-installed Xdebug, but if you try to use it, you may find that it errors. In order to make it work, the debugger needs to be compiled manually.
- Clone Xdebug using
git clone git://github.com/xdebug/xdebug.git.
- Now run
phpizeinside the directory.
- If everything went good, you should see something like this:
Configuring for: PHP Api Version: 201603003 Zend Module Api No: 201603003 Zend Extension Api No: 320160303
makecommands one after the other.
- To workaround traditional installation approach of xdebug.so, we will install the extension to the
mkdir -p /usr/local/php/extensions cp modules/xdebug.so /usr/local/php/extensions
- Lastly find the
php.inifile and add
- To test it, run
php -i | grep xdebug. The output should begin with:
xdebug xdebug support => enabled ....
Ubuntu (16.04.4 Xenial)¶
- UPDATE PHP TO THE LATEST VERSION or find the right xdebug version for your php version
- https://xdebug.org/wizard.php Paste PHPINFO html here in here to get bespoke installation instructions
- Download xdebug 2.5.3 or better depending on your PHP version from the webpage. Use https://github.com/xdebug/xdebug/releases
- Cd into the extracted folder and then install the extension using the php extension installer
- make && make install
- Add the xdebug.so to php.ini
[Xdebug] zend_extension = "/opt/lampp/lib/php/extensions/no-debug-non-zts-20170718/xdebug.so" xdebug.remote_enable = 1 xdebug.remote_autostart = 1 xdebug.remote_handler = dbgp xdebug.remote_mode = req xdebug.remote_host = 127.0.0.1 xdebug.remote_port = 8123 xdebug.max_nesting_level = 300`
Finally restart the server and check
phpinfo and you should have an xdebug section