Installing Zend Z-Ray on Homestead
Laravel Tutorials / updated: July 19, 2016

Installing Zend Z-Ray on Homestead

For the past week or so I have been running Zend Z-Ray in Laravel Homestead. Every time using it, new features come to light that are fantastic for debugging your apps in development! What follows is a quick preview of Z-Ray, along with all the steps necessary to install it on Laravel Homestead.

Overview

Z-Ray installs on the server, and will automatically load on all your projects on that particular server (in our case Homestead) automatically. Even better, it supports many major frameworks right out of the box, including: WordPress, ZendFramework (1 & 2), Magento, Drupal, with Symfony support on the way. (You can even extend it for your own Framework, if you like!)

This is very exciting for developers who have all their client sites in Homestead, regardless of the framework. The bottom line is that Z-Ray saves time and provides debugging tools without requiring you to install them in each project.

General Features of Z-Ray

Page Requests lets you specify the context of the ZRay panel, allowing inspection of AJAX requests.
Page Requests lets you specify the context of the ZRay panel, allowing inspection of AJAX requests.
Execution Time and Memory peak give you insight into server usage.
Execution Time and Memory peak give you insight into server usage.
Errors & Warnings is pretty self-explanitory. However, notice that you can inspect @-silenced errors here as well!
Errors & Warnings is pretty self-explanitory. However, notice that you can inspect @-silenced errors here as well!
Database Queries is one of the most useful features. And remember, you can inspect the queries of AJAX calls as well
Database Queries is one of the most useful features. And remember, you can inspect the queries of AJAX calls as well
The Functions view lists all functions that are processed on any given request, providing insight into the execution chain.
The Functions view lists all functions that are processed on any given request, providing insight into the execution chain.
Request Info tab displays the usual request information we can see in modern browser inspection panels. It also includes PHP super-globals, which is super helpful!
Request Info tab displays the usual request information we can see in modern browser inspection panels. It also includes PHP super-globals, which is super helpful!

Laravel Features in Z-Ray

General Laravel project information.
General Laravel project information.
Route inspection providing you with everything you need to know about the route hit by the selected request.
Route inspection providing you with everything you need to know about the route hit by the selected request.
The Session inspector lists all the pertinent data, including any errors or messages.
The Session inspector lists all the pertinent data, including any errors or messages.
User Information — while self-explanatory, definitely useful for debugging and inspecting anything Auth::user related.
User Information — while self-explanatory, definitely useful for debugging and inspecting anything Auth::user related.
Views gives you insight into which views are rendered, including details as to the path of the view, and which variables are passed into the views (along with the values, of course).
Views gives you insight into which views are rendered, including details as to the path of the view, and which variables are passed into the views (along with the values, of course).
Events Log makes event debugging easy! Check out which events were fired, and in which order
Events Log makes event debugging easy! Check out which events were fired, and in which order

Admin Panel

The admin panel can be easily accessed from the Z-Ray bar itself via the right hamburger menu and selecting “Settings”, or you can browse any of your homestead sites with the admin port 10081, for example http://example.dev:10081/.

Z-Ray’s admin panel provides a wealth of information and configuration options. The home page gives a nice overview of the features.
Z-Ray’s admin panel provides a wealth of information and configuration options. The home page gives a nice overview of the features.
Z-Ray Live! is an interesting features that lets you monitor live activity on your site. This could be useful for behind-the-scenes monitoring of events on live servers.
Z-Ray Live! is an interesting features that lets you monitor live activity on your site. This could be useful for behind-the-scenes monitoring of events on live servers.
Access Mode lets you configure how you want Z-Ray to appear on your server, including hiding it from the site front-end, while still collecting data in Z-Ray Live!
Access Mode lets you configure how you want Z-Ray to appear on your server, including hiding it from the site front-end, while still collecting data in Z-Ray Live!
Here you can inspect previous HTTP requests.
Here you can inspect previous HTTP requests.
The Settings page lets you further fine-tune how Z-Ray operates on your server.
The Settings page lets you further fine-tune how Z-Ray operates on your server.

Installation

Requirements

Guide

SSH into your homestead environment, and make sure you are in your home folder:

homestead ssh
cd ~

Let’s download Z-Ray:

wget http://downloads.zend.com/zray/1208/zray-php5.6-Ubuntu-14.04-x86_64.tar.gz

Enter super-user mode:

sudo su

Unzip the archive:

tar xvfz zray-php5.6-Ubuntu-14.04-x86_64.tar.gz -C /opt

Create a new file /etc/nginx/conf.d/zray.conf:

server {
  listen 10081 default_server;
  server_name _;
  server_name_in_redirect off;
  root /opt/zray/gui/public;
  index index.php index.html index.htm;
  location ~ ^/ZendServer/(.+)$ {
    try_files /$1 /index.php?$args;
  }
  location / {
    try_files $uri $uri/ /index.php$is_args$args;
  }
  location ~ \.php$ {
    fastcgi_pass unix:/var/run/php5-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
  }
}

Create symlinks to PHP configurations:

ln -sf /opt/zray/zray.ini /etc/php5/cli/conf.d/zray.ini 
ln -sf /opt/zray/zray.ini /etc/php5/fpm/conf.d/zray.ini

Verify Z-Ray is running:

php -v

Inside the with sections you should see Z-Ray listed:

with Zend Server Z-Ray v8.5.0

Now, we need to set permissions on the Z-Ray files so the web server can access them:

chown -R vagrant:vagrant /opt/zray

And finally, lets restart NGINX:

service nginx restart

You can now exit out of super-user mode (CTRL-D). Before we leave Homestead, let’s clean up after ourselves:

cd ~
rm -rf zray*

And now exit out of homestead (CTRL-D again). We’re almost there. We just need to edit the Homestead configuration to open the Z-Ray admin port:

homestead edit

And add the following lines under the cpus directive:

ports: 
    - send: 10081 
      to: 10081

Let’s restart and provision Homestead:

homestead halt
homestead up --provision

Now simply access any of your homestead sites like you normally would under port 8000, and you should see the Z-Ray bar at the bottom.

If Z-Ray does not load and you are getting a 500 error in your browser console, it may be necessary to re-apply the permissions to the Z-Ray folder:

homestead ssh
sudo chown -R vagrant:vagrant /opt/zray

When done, hit CTRL-D or type exit to leave homestead, and try loading it in your browser again. This should fix it.


Uninstallation

To uninstall it, we simply reverse the process:

sudo -i
rm /etc/php5/cli/conf.d/zray.ini 
rm /etc/php5/fpm/conf.d/zray.ini
rm /etc/nginx/conf.d/zray.conf
rm -rf /opt/zray

Now exit out of Homestead and remove the 10081 port from your Homestead.yml file.
After that, halt and restarting Homestead should be the finishing touch.

homestead halt && homestead up

I want to thank Zeev Suraski from Zend for inviting me to test-drive their tech preview of the stand-alone version of Z-Ray.

We would love to hear about your experiences with Z-Ray! Do you like it? Does it improve your development workflow? Let us know.

Laravel News Partners

Newsletter

Join the weekly newsletter and never miss out on new tips, tutorials, and more.