Developing a Z-Ray Plugin 101

      4 Comments on Developing a Z-Ray Plugin 101

One of the great things about Z-Ray is the ability to extend it to display any info you want about your app. This is done by creating plugins.
In this tutorial I’m going to describe how to create a new Z-Ray plugin. I’ll be supplying code snippets to insert in the various plugin files but of course feel free to replace it with your own code when possible.

Introduction

Z-Ray tracks the data you decide you want to see during development and displays it in separate panels.

There are two options for creating Z-Ray panels.

The first option is to use Z-Ray default panels. Default panels are created automatically, and Z-Ray’s internal mechanism selects the appropriate way of displaying the data.

The second option is to create your own custom panel.  In a custom panel you can display almost anything you want using HTML, CSS and JavaScript. In custom panels you can also pull data from Z-Ray’s storage mechanism and use Z-Ray widgets to display the data.

In this tutorial, we’re going to do the following:

  1. Create a simple dummy custom panel with no data whatsoever.
  2. See how to trace data using Z-Ray’s trace functions, and how to display this data in a “native” panels.
  3. Learn how to use Z-Ray data in custom panels and how to use Z-Ray’s JavaScript functions.

Note: To follow the steps in this tutorial you will need Zend Server 8.5 and above. If you are using the Z-Ray technology preview, the process is identical but take into consideration that the file paths may differ.

Step 1 : Creating “Hello World!”

First, I’m going to create a simple PHP file in my /var/www folder. This file will simulate the code I want to introspect using Z-Ray and the new plugin we’re about to create. I’m going to name this file ‘hello.php’ and add  the following simple HTML content:

Open the file in your browser to take a look at your new app, and make sure Z-Ray is displayed at the bottom of your page.

Step 2 : Creating the Plugin

Now that we have the “app” we want to profile using Z-Ray, let’s create the new plugin.

First, we need to create a folder in /usr/local/zend/var/plugins with the name of the plugin. This folder contains all the Z-Ray plugins that come bundled with Zend Server and that are already installed in your system.

I will name the new folder ‘hello_world’ ( /usr/local/zend/var/plugins/hello_world).
In this new folder, I’m going to create a subfolder called ‘zray’ to contain the plugin files (/usr/local/zend/var/plugins/hello_world/zray), and within this subfolder, I’m going to create two new files: ‘zray.php’ and ‘Module.php’.

For now, let’s keep the ’zray.php’ file empty, but we’re going to add the following content to the ‘Module.php’ file, creating a new custom panel, named ‘hello’:

Next, I’m going to create a view file for the custom panel, with the same name as the panel. The view file contains all the custom functionality that you want Z-Ray to read and display in the panel. This could be simple HTML or more complex JavaScript and CSS functionality. Each custom panel you create for your plugin should have its own view file.

Create a ‘Panels’ folder under the ‘zray’ folder ( /usr/local/zend/var/plugins/hello_world/zray/Panels/), and a ‘hello/phtml’ file (/usr/local/zend/var/plugins/hello_world/zray/Panels/hello.phtml) with the following content:

The view file contains all the custom functionality that you want Z-Ray to read and display in the panel. This could be simple HTML or more complex JavaScript and CSS functionality. Each custom panel you create for your plugin should have its own view file.

Refresh  the ‘hello.php’ file in your browser. You’ll notice that Z-Ray now displays a new panel. Congratulations! You have successfully created your first Z-Ray plugin!

Step 3 : Tracing Stuff

The previous step helped us understand the basic structure of the plugin. Our next step is to understand how to trace functions and the basic way in which Z-Ray collects data on methods, functions and the object model.

Change the content of your app at /var/www/hello.php as follows:

The code above is a dummy class, with static and non-static methods and properties which I’m going to use in my demonstration. Please keep in mind that the order of the code is very important when debugging. In this case, I’m calling a static method before creating an instance of the class.
Open the file in /usr/local/zend/var/plugins/hello_world/zray/zray.php and change it so it looks like this:

Refresh your app in the browser.

Two new tabs are added to your plugin, tracing data as prescribed in the code we inserted.

Let’s take a closer look at the code.

This line of code creates the Z-Ray extension, and names it ‘HelloWorld’.

This line enables the extension after a call to DummyClass::setT1 – in our case on /var/www/hello.php – but it will be enabled for any file calling DummyClass::setT1, and in any context.
The common scenario is to use ‘setEnabledAfter’ for a specific application (i.e. using wp_initial_constants for WordPress apps).

This line creates a new instance of the Trace class, which is a custom class I’ve created in the same file to handle the tracing data.
The class has 3 methods.
The ‘onEnter’ method is a dummy function that is not actually doing anything but is still required by the Z-Ray API.
The second method, ‘onLeaveSetT1’, adds the context data to the SetT1Calls panel and the ‘onLeaveConstruct’ method adds object data to the DummyClass panel. Both methods have two parameters, and the storage parameter is used by reference.
This is the core logic of how Z-Ray traces and displays data. Z-Ray uses the context to send all the context data of a function, including the instance of the class that the method is called on. This feature is extremely powerful and can help you retrieve data that is otherwise almost impossible to get.

The first argument sets a trace on DummyClass::setT1. The second argument is the function called when entering the function (onEnter), and the third argument (onLeaveSetT1) is called when it’s done.
The first entry to the array is the instance of the class I’m using. The methods are called each time the traced method is called with the storage (reference) and context parameters. The context will contain all the related data, including the $context[‘this’] argument which will contain the object if the method is called on an object.
The context includes a lot of data that can be very helpful in debugging complex scenarios and can help you debug very complex application workflows, including the state of each object over the running process of an application.

Step 4 : Z-Ray JavaScript and Data Collection

Up until now, we’ve created our new plugin and told Z-Ray which data to trace and display. Our next step is to use Z-Ray’s display the data in custom panels using JavaScript.

To display the data we’re collecting with Z-Ray in a custom panel, we first have to send the data to storage.

I’m now going to add a new function that will return some simple array data.

Let’s change /var/www/hello.php as follows:

Next, let’s change the content of /usr/local/zend/var/plugins/hello_world/zray/zray.php so it will add the new data to the storage.

We just added a new ‘JsData’ panel. Since we do not want to display the new panel as a default panel, I’m now going to hide it.
To do this, I’m going to change the configuration in /usr/local/zend/var/plugins/hello_world/zray/Module.php as follows:

Now, I’m going to add the JavaScript code that will pull the data and show it in a Z-Ray table widget and also output it to the browser console.
In /usr/local/zend/var/plugins/hello_world/zray/Panels/hello.phtml, paste the following code:

First, I’m creating an array with the basic table configuration. Then, I’m using PHP to output the table widget, and JavaScript to pull data from the storage and show it in the table widget. I’m also sending the same data to the JavaScript console.
Refresh the page.
You’ll see that the Hello World panel now displays the traced data inside a Z-Ray table which was the widget we selected to use for displaying the data. Of course, you could have displayed this data in any way you wanted to using JavaScript and CSS.
If you open the browser console you will also notice the JavaScript objects outlined.

Conclusion

This tutorial shows some of the basic steps for creating custom Z-Ray plugins for your own code. You can of course use the same techniques that are used in this tutorial to debug any project, in any scale.
To be able to install and manage plugins easily in Zend Server, and share them with other developers and Z-Ray users via the Zend Gallery, plugins need to be packaged.
The easiest way to create a package for your plugin is to use the Skeleton plugin (see link below). The Skeleton plugin also contains usable code that you should understand how to use after this tutorial.

Additional Resources