Debugging Joomla with PhpStorm and Xdebug

Debugging is inevitable. Whether you do it right or wrong, you will always end up trying to figure out what is wrong with your code. It does not matter how skilled you are, your code will contain bugs! That is a fact.

Sometimes these are easily spotted by just using a var_dump, print_r and/or die statement. I still use those sometimes, no shame on that. However, when code gets complex you need to have the right companion at your side. My companion is called PhpStorm.

PhpStorm project

For working or even debugging code in our development environment we need to create a project in PhpStorm.

Open PhpStorm and create a new empty project by selecting the Projects directory. PhpStorm will prompt a message letting you know that the folder already contains some source code. Click Yes to continue.

You now have access to all of the files and folders available in the ‘Hello World’ component.

External libraries

Having access and debugging the Joomla site source code is also very useful. For this we need to add the entire site as an external library:

Right click on External Libraries under the file explorer.

Click on Configure PHP include Paths. This will open a new dialog for introducing paths of libraries being used in your project.

Click on the plus sign (+) and add the www/debug directory located in the box install directory.

Click on OK to save and quit.

www is another shared directory that gets automatically created when you install the box. It exposes the source code of our Joomla debug site and can be browsed using the file explorer.

Path mappings

We also need to tell PhpStorm about path mappings. These are used by PhpStorm to map local project files to those located in our remote server.

Open the Preferences window under the PhpStorm menu.

Click on Language & Frameworks => PHP => Servers.

Click on the plus sign (+) to define a new configuration. The name and host should point to joomla.box.

Active the Use path mappings checkbox.

Set the following mappings:

/path/to/your/Projects => /home/vagrant/Projects

/path/to/your/www => /var/www/debug

Click on OK to save and quit.

Additionally, and still while on the PHP settings, go to the Debug configuration area and make sure to disable the option Force break at the first line when no path mapping is specified under the Xdebug section. This will avoid unwanted breaks due to absent path mapping from system requests such as those from Z-ray.

At this stage our development environment is set. We are now ready for debugging real code!

Debugging

To start a debug session in PhpStorm you need to click on the little bug phoning home icon located in the toolbar. Make sure the little bug is green which means that PhpStorm will listen for incoming debugging connections.

With PhpStorm properly configured for debugging we now need to add one or more breakpoints somewhere in the code. To add a breakpoint open the administrator/components/com_helloworld/helloworld.php file using the PhpStorm file explorer and make a click on the grey column at the left of the echo 'Hello World!'; statement:

The red circle means that you’ve added a breakpoint. PhpStorm will stop the script execution at that particular line.

Start an Xdebug session

Open the following URL in your browser with username & password: admin:

PhpStorm will now gain control of the execution of the script and the debug panel will pop-up.

The XDEBUG_SESSION_START variable in the previous URL tells Xdebug that we are initiating a debug session. An even more convenient way if you use Chrome is to install the Xdebug helper to initiating the debug and profiling sessions with a single click.

Debugger panel

The debugger panel shows a call stack as well as a list of context variables in the left and right columns respectively. You can even watch some variables by just dragging them from the Variables to the Watches container.

The panel’s toolbar has common debugging action buttons such as Step Over (step to the next line in the current file) and Step Into (Step to the next executed line).

One of my favorites is the Evaluate Expression feature. You can access this tool by clicking on its toolbar button . You’ll get a new dialog for evaluating expressions in the current context. You can also watch an evaluated expression by using Ctrl+Shift+Enter from within this window.

Another useful feature is the possibility of adding conditional breakpoints. You just make a breakpoint conditional by right clicking on it and adding a condition such as $result === false. In this scenario PhpStorm will only stop execution if the condition is met.

Debug the right way

Developers should concentrate on what they do best which is writing awesome code. For writing great software you need to have the right tools at your disposal.

PhpStorm provides a straightforward interface for debugging code. It also provides a clean and top notch code editor with lots of features. Its integrated debugging interface also makes for an excellent testing and learning tool. Being able to execute code step by step with complete awareness of the context (variables, call stack, etc.) is golden.

Debuggers exist and you should use them. Once you have tried it, there is no coming back. That is also a fact!

Happy coding!

Up next

Coming soon! Our next Joomla! contribution

Celebrating Joomlatools open sourced code as we prepare to release our next Joomla! contribution.