Developing a Z-Ray Extension

Note: The information in this article applies to Zend Server version 8.0 or earlier.  File locations and structures have since changed.  For current information about how to write a Z-Ray plugin, please see http://devzone.zend.com/6149/develop-your-first-zend-server-plugin-part-1/

One of the coolest features in Z-Ray is the ability to plug in your own extensions. Meaning, you can customize existing Z-Ray panels or add your own personalized Z-Ray panel for displaying information you think is important for developing your specific application. 

This short tutorial will describe how to write a basic extension for Z-Ray. More specifically, we’ll be writing a Z-Ray extension for WordPress that extracts and displays a list of loaded WordPress plugins.

All the documentation you need to learn how to build a Z-Ray extension is detailed beautifully on GitHub.

Note: You will be provided with code snippets throughout this tutorial. The complete code example appears at the end.

Prerequisites

To follow the steps in this tutorial, you will need to do the following:

  • Download, install, and launch Zend Server 8.x.
  • Move/delete the existing built-in WordPress Z-Ray extension located at:
    • Mac and Linux: /usr/local/zend/var/zray/extensions/
    • Windows: C:\Program Files (x86)\Zend\ZendServer\data\zray\extensions\
  • Install WordPress on Zend Server.

Step 1: Creating the ‘zray.php’ File

Your first step is to go to the Z-Ray extensions folder in your Zend Server installation files, and create a new folder with the name of your extension (e.g.,WordPress). See the Prerequisites section above for the location of this folder.

In this folder, create a new PHP file called ‘zray.php’.

This file is the Z-Ray extension include file, and it’s good practice to have it in the root of the extension directory.

Step 2: Declaring the New Extension

In the newly created ‘zray.php’ file, you’re now going to enter a class for declaring the new extension:

This class is the main API for defining all the extension’s trace actions and metadata, and can be instantiated for as many extensions as necessary.

Step 3: Enabling the Extension

Next, you’re going to enable the extension. There are a number of ways to do this, but the safest way about it is to use the following expression:

We’re basically telling Z-Ray to load the extension after the ‘wp_initial_constants’ method –  the first WordPress function on a page – is called.

Step 4: Declaring a Trace

The next part is to declare a trace on a particular function. This is the main functional part of the extension as it defines the function to be traced and the data to be displayed in Z-Ray.

The declaration  includes the name of the function to be traced, and two callables which are fired when entering and exiting the function. Something along the lines of:

In our case, we’re going to trace the ‘wp_cache_close‘ function since we know this is a good time to retrieve the plugins.

I’m going to leave the entry callable empty as I have no use for it, but I am going to develop the exit callable a bit.

First, I’m going to add the two parameters that the traceFunction callable method accepts:

  • $context is an array of information about the function
  • $storage is a reference to the storage array, and is used to store the info that will actually be displayed in Z-Ray.

Next, we’re going to code what we want executed upon leaving the  ‘wp_cache_close‘ function. We’re going to start by entering the WordPress method for extracting plugin data.

Now, since we don’t really know what this data actually looks like, we’re going to first dump the $plugins object in a new Z-Ray panel and check out what it looks like in Z-Ray. The way to do this is very simple:

Save the file, and open WordPress in your browser.

pluign_var_panel

You’ll notice that a new panel was automatically added to Z-Ray with a tree table displaying a multi-level array. The extension’s storage mechanism automatically generates tables based on the information stored. If an array or associative array is passed, a grid table will be created with columns as the names of the keys. If a multi-level array or an object is passed, a tree table will be created.

Now, we’d like to extract only part of this information, say only the name and version of the plugin.

So we’re going to enter a ‘foreach’ loop with another storage execution, only this time we’re going to specify an array instead of the $plugins object.

Save the file, and refresh WordPress again.

plugins_panel_without_wp_icon

You can now see a new Plugins panel with a grid view of the plugins, and with the info we wanted to be displayed.

Step 5 : Adding a Logo

If not specified otherwise, extensions will display the Zend logo on Z-Ray and in the extension panels themselves. However, a nice touch to an extension is to add your own logo.

To do this, you’ll first need to add the logo image to the folder containing the extension file. Please note that the image should be 24X24 px, and should contain both a regular and hover state.

Next, in the extension file, we’re going to use the setMetadata function. In this case, we’re going to use the unique key ‘logo’ to set the default logo for the extension. This is done by passing a full path to the logo file:

Save, and refresh WordPress.

plugins_panel

——————————————————————–

Cool! How easy was that?

This is what your code should look like at the end:

So whatever app you’re working on, whatever framework or platform – you can make Z-Ray trace and display the info you want.

Enjoy!

The following two tabs change content below.

    Daniel Berman

    Product Evangelist at Zend Technologies. Passionate about PHP, Zend's products and family. Into running, Liverpool FC, and blogging.

    About Daniel Berman

    Product Evangelist at Zend Technologies. Passionate about PHP, Zend's products and family. Into running, Liverpool FC, and blogging.