Debugging Joomla with the Joomlatools Box and Z-Ray

This article introduces a new and easy way to develop and debug Joomla applications using the Joomlatools vagrant box and Z-Ray.

The team at Joomlatools created a preconfigured Vagrant box to allow Joomla developers to easily set up a complete local development environment using a PHP stack, Apache 2.4, MySQL 5.5, and a rich set of developer tools, including a management console, Composer, PhpMyAdmin, Wetty, and more.

This box now also includes Z-Ray, Zend’s advanced debugging and productivity tool that was announced as a separate component during ZendCon in October (Z-Ray is still shipped with Zend Server as well).

The package is wrapped up nicely, so you don’t have to set up Vagrant or configure Joomla.

What this all means is that Joomla developers now have easy access to a comprehensive development environment that includes the tools and technology they need to be able to focus solely on their code.

Installing the Joomlatools Vagrant box

So the first thing you’re going to do is set up the Joomlatools vagrant box.

To do this, you’ll need Vagrant installed of course. Then, create a new folder to contain the project, access it, and issue the following commands to download and initialize the box:

Next, add the following line into your ‘hosts’ file:

You can now access the Joomla box dashboard at:


The dashboard is a useful way to manage and access the tools included in the box which are listed on the menu on the left.

Creating a sample site

Before we start to use Z-Ray, we need some code to use it on! To do this we’re going to create our very first Joomla site.

You can SSH into the box or use the supplied Wetty terminal (accessed at: to enter the following command:

The box will then download and install a new Joomla 3.4.5 application. Refresh the Joomla box dashboard and you’ll see your new app displayed.


Z-Ray for Joomla

Open your Joomla application using the credentials supplied in the terminal: admin/admin.

At the bottom of the page, you’ll notice a nifty toolbar displayed. Hello Z-Ray!


Z-Ray tracks and displays information on all the various PHP elements constructing your page, including page requests, memory consumption, errors, warnings, exceptions, functions, database queries, and more.

One of the more exciting features about Z-Ray is the ability to extend it to show any piece of information you’d like to expose during development. Z-Ray extensions are called plugins, and in this case, you’re seeing two such plugins: a Composer plugin and a Joomla plugin.

Open the Joomla plugin by simply selecting it in Z-Ray.


While Z-Ray plugins usually require installation via the Plugins Gallery (see below for more details), the nice guys at Joomlatools made sure the Joomla plugin is enabled by default so no further steps are required on your part.

The Joomla plugin for Z-Ray was developed by Jisse Reitsma from Yireo, and can be found on GitHub here: . You can find a full overview of this plugin here .

Additional goodies

While the information displayed by Z-Ray is extensive, you can find additional functionality in Z-Ray’s management dashboard.

To access this functionality, go back to the Joomla box dashboard, and from the menu on the left, select Z-Ray.


Z-Ray Live!

On this page you can use Z-Ray to debug non-browser based requests such as those initiated from mobile clients, APIs and CLI calls.


The History feature allows you to go back in time and use Z-Ray take a look at requests made in the past.


If you’re wondering how to configure the way Z-Ray collects and displays data, this is the place. On the Settings page, you can configure data collection, privacy and other advanced settings.

-The End-

So, in just a few minutes, you can set up a full Joomla development environment which includes Z-Ray.

Z-Ray as a standalone offering outside of Zend Server is still a tech preview only. We’d love to hear from you guys on whether you think Z-Ray is useful and whether you have any ideas for improving it. If you do have any feedback, please send it to: