Skip to content

How to debug PHP applications

This guide covers three ways to debug PHP applications:

  1. Debugging from within Homestead
  2. Debugging by viewing a PHP object in Chrome
  3. 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.

Installing Xdebug

Install the Xdebug on Homestead by first logging in as super user.

sudo apt-get install php-xdebug

Open /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 /etc/php/your_php_version/cli/conf.d/20-xdebug.ini. If it does not exist, enable the xdebug module with:

sudo phpenmod xdebug

To confirm that Xdebug was set up correctly, run:

php -m

to list all your installed PHP modules, and look for Xdebug.

Configuring PHPStorm

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. For instance, /home/vagrant/Projects/my-project.

Add the Xdebug extension to your browser and enable it. Xdebug Helper for Firefox or Xdebug helper for Chrome are both free.

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:

  1. Download Debugging.php and add the class to your project.
  2. Call the phpObjectToChrome() function and pass in the appropriate arguments (see below).
  3. Open the dev tool in the browser (Ctrl+Shift+I in Chrome) and the PHP object should be there.

Example

Debugging::phpObjectToChrome($request, '$request');

chromeExample

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_backtrace for all the calls that are made to the PhpObjectToChrome function.

Procedure

  • Store the backtrace in $fullTraces
  • Convert the PHP object ($object) to an array using the PHP objectToArray() function.
  • Convert the arrays to JSON objects so that they can be used in the Javascript. Javascript cannot understand PHP objects, however, it works well with JSON objects so the PHP objects have to be converted.
  • 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 $shortCallInfoClass. I did this because Javascript does not let me echo data by specifying its position in the PHP array but it does let me echo a single variable.

Output

  • Echo will be used to create Javascript scripts that return the values gathered by this function.
  • Use console.log() to return the short information for this call. This includes values such as the class name, file name etc.
  • Also, console.log() the JSON version of the $object. Javascript automatically converts JSON objects to array so there's no need to parse the $objectJson.
  • Convert the current array of jsonFullTraces into a Javascript array in case the user requests them.
  • echo a Javascript function that returns the full backtrace for a function. The user will call this function and give the id of the call they want to get the full trace for.

Debugging on your local machine (i.e. without Homestead)

The following sections describe how to install and configure Xdebug for a specific operating system.

Windows

  1. Go to this page and download the correct 32/64 bit version. Do not get the non-TS version.
  2. In your php.ini file (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 ;extension=xdebug.

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.

  1. Clone Xdebug using git clone git://github.com/xdebug/xdebug.git.
  2. cd xdebug
  3. Now run phpize inside the directory.
  4. 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
  1. Execute ./configure and make commands one after the other.
  2. To workaround traditional installation approach of xdebug.so, we will install the extension to the usr/local folder:
mkdir -p /usr/local/php/extensions
cp modules/xdebug.so /usr/local/php/extensions
  1. Lastly find the php.ini file and add zend_extension=/usr/local/php/extensions/xdebug.so.
  2. To test it, run php -i | grep xdebug. The output should begin with:
xdebug
xdebug support => enabled
....

Ubuntu (16.04.4 Xenial)

  1. UPDATE PHP TO THE LATEST VERSION or find the right xdebug version for your php version
  2. https://xdebug.org/wizard.php Paste PHPINFO html here in here to get bespoke installation instructions
  3. Download xdebug 2.5.3 or better depending on your PHP version from the webpage. Use https://github.com/xdebug/xdebug/releases
  4. Cd into the extracted folder and then install the extension using the php extension installer
  5. phpize
  6. ./configure
  7. make && make install
  8. 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

PhpInfoXdebugSection

Further reading