Setting up local step debugging with PhpStorm

Setting up PHP debugging in an IDE with a local development environment has gotten so easy it can be done in a few automated steps. In this post I will demonstrate how to get step debugging functioning with PhpStorm and Zend Debugger when the server is set up on a local environment.

To begin with, I had the following:

  • Local installation of Zend Server 8.5.+ (basic LAMP stack, but with Zend Debugger included in the Zend Server installation). Alternatively I could have had a vanilla LAMP environment with Xdebug.
  • Ensure that Z-Ray is active in the Zend Server settings.
  • A local project set up on PhpStorm, without the server set up in the PhpStorm project configuration. (in this example I have a Zend Expressive Skeleton ready)
  • The local project set up as an Apache virtualhost.

With the project open in PhpStorm I click the icon to inform the IDE to start listening for debugging sessions. (Usually in the upper right corner, looks like a telephone receiver with a red indicator that it is not listening, and turns green when you click it)

Then a browser with the application rendered I click the debug icon in the Z-Ray toolbar at the foot of the window, and select the desired debugging action.

This will cause PhpStorm to prompt after it receives the debug connection from Zend Debugger. In most cases we can simply click Accept and let things happen normally.

That’s about it, we are debugging!

Behind the scenes, PhpStorm created a site and associated it with the project.

Of course we could have created the server ahead of time and not be prompted to Accept the incoming connection, but what is the fun in that?

Closing

This was a very simplistic local development environment setup. We didn’t have a firewall to contend with, and the server was set up locally rather than inside a virtual machine. I have other posts, linked below, to help with some of these alternative setups.

Happy Debugging!

Other posts on Debugging you may find helpful:

Using an SSH tunnel to step debug through a firewall

In a previous post I covered how to set up PHP step debugging in Zend Studio. But if that doesn’t work there may be a firewall in between the server and the debugging client, or IDE, preventing the connection. Here is a possible way to get around that.

Note: Of course there is no way to avoid the firewall, but this post assumes a connection to the server using SSH is possible. What we’ll do is allow communications from the server to the client using the Zend Studio default debugging port (10137) forwarded through an SSH tunnel which uses port 22 by default. For this to work an SSH connection must be possible from the client to the server.

While it is possible to do this using command line from Linux or Mac, or using PuTTY on Windows, this example will use the built-in SSH capabilities of Zend Studio 13. For older versions of Zend Studio I recommend using command line or PuTTY linked above.

Assuming step debugging in Zend Studio was already set up as outlined in my previous post we will continue using that setup, but enhance it with an SSH tunnel.

In Zend Studio open the preferences. (Windows|Preferences) With the preferences open, expand the PHP node to get to Servers. Highlight the server configuration to work with, and click Edit.

Screenshot from 2016-04-18 15:07:40

When the Edit Server dialog opens select the SSH Tunneling tab. Check the box to Enable SSH Tunneling, and populate the desired Username and Password. If your server requires the use of an SSH Private Key in order to login, please supply that.

Screenshot from 2016-04-18 14:41:34

Now that the SSH connection is set up we need to add the Port Forwarding for the debugging port. Do this by clicking the Add button in the Port Forwarding section.

Screenshot from 2016-04-18 14:43:45

Select ‘remote’ to specify which side of the tunnel will be sending communication on the forwarded port, enter the local address the remote side (server) will use and port number to send to. Then enter the port number on the receiving end (the client). Now click Finish to apply the setup, and click finish to exit the preferences.

In the PHP Servers view (Windows|Show View|PHP Servers) right-click the server we just added SSH Tunneling support to and select Open SSH Tunnel. You should then see a brief dialog letting you know the connection was made.

Screenshot from 2016-04-18 14:52:41

We are ready to debug!

Since I was using Zend Server in this example I have Z-Ray available, and while on a page I wished to debug I could simply click on the debug icon and select any of the debugging options.

Screenshot from 2016-04-03 15:24:13

This will cause Zend Debugger to contact Zend Studio for debugging, which in turn will ask the user if they wish to open the debugging perspective.

IMPORTANT NOTE: Debugging over an SSH tunnel is not fast. Therefore you may notice a lag between initiating the debug session and your IDE reacting. After that things speed up, but the initial connection is slow on many networks.

Screenshot from 2016-04-03 15:24:44

If Yes is selected the IDE is now ready to perform any debugging the user desires.

Screenshot from 2016-04-03 15:27:24

Happy debugging!!!

This post is one in a series on debugging. For others click below:

PhpStorm and debugging issue
Setting up step debugging in Zend Studio
Setting up local debugging with PhpStorm

Setting up remote step debugging with Zend Studio

Recently I was helping someone set up step debugging of PHP in Zend Studio to debug a remote site, and had some difficulties. So I decided to create this post to remind me later, and perhaps help others get it set up.

I was doing this on an Ubuntu laptop, so while menus may vary slightly the process should be very similar regardless of OS. Also, I did this using a local VirtualBox virtual machine, using Bridged networking mode to simulate a remote server. In Zend Studio I had a project created with the Zend Framework Skeleton Application, and created a virtualhost in the virtual environment that mirrored that.

NOTE: If the desire is to use a local server the setup is much simpler.

Server setup

While this post doesn’t cover how to install Zend Debugger or Xdebug, ensure one of these are set up correctly. Also, ensure the debugger of choice “knows” where to find the IDE to be debugging from. Zend Debugger can try to do this automatically, or an IP can be manually specified within Zend Debugger or Xdebug. Also, if using Zend Debugger ensure the IP of the client is added to the whitelist. More on how to verify this IP from the client later.

Aiming at the server

The first step, assuming you already have a project created in Zend Studio, is to add a server to the project configuration. Do this in the preferences. (Windows|Preferences)  With the preferences open, expand the PHP node to get to Servers.

Screenshot from 2016-04-03 15:17:07

From there click “New”, and follow the wizard for setup. The first step is to specify the type of server. In my case I was using an install of Zend Debugger that comes with Zend Server, so selected Remote Zend Server. Alternatively I could have easily selected Generic PHP Server to arrive at the same endpoint later.

Screenshot from 2016-04-03 15:17:47

Next, after giving this server a name and URL (ensure the URL actually hits the server), I am prompted for the Zend Server login credentials to gain access to the Zend Server Web API.

Screenshot from 2016-04-03 15:19:09

Entering the user and password authorizes Zend Studio to pull down an API key for interacting directly with Zend Server if I desired to later. (This creates a new Zend Server Web API Key on the server specifically for this client.) Alternatively it is possible to click Cancel and enter the credentials manually.

Again, this is not really required for simply debugging, but I’m including it for completeness sake.

Screenshot from 2016-04-08 09:25:43

At this point a test can be run to ensure we are hitting the server as expected by clicking the Test button.

NOTE: If this doesn’t end in a success you may have some network issues to overcome. See my post on using an SSH Tunnel if you need to.

Screenshot from 2016-04-03 15:20:12

After a success, click OK and then Finish the wizard. If you had troubles, please see my post for using an SSH tunnel.

Enable debugging for the project

With the server set up it is now possible to set up debugging for the Zend Studio project.

In the Preferences (Windows|Preferences) click on the Debug within the PHP node.

Screenshot from 2016-04-03 15:21:16

Though it is possible to specify the PHP Server globally from the resulting option screen I prefer to set up preferences for each project, since most of my projects may be different in any way. So I click Configure Project Specific Settings… link at the top of the dialog and am prompted to specify which project I desire to configure.

Screenshot from 2016-04-03 15:21:57

After selecting the appropriate project I can then appoint the server I just added above, and then specify the Base Path and ensure the Auto-generated Base URL is correct in the lower section.

Screenshot from 2016-04-03 15:22:26

After approving and closing the Preferences, we are ready to debug!!!

Test: If the following step doesn’t work it may be because the debugger on the server cannot find the IDE. In a browser check what ports the IDE is listening on by entering the following URL to hit Zend Studio’s built in web server.

Screenshot from 2016-04-08 09:48:52

If the debug_host doesn’t show an IP address reachable by the server then it may be necessary to manually specify the IP in Zend Studio by altering the server configuration we created previously.

If the IP address should be reachable by the server the issue may be in the configuration on the servers end, or perhaps a firewall or load balancer in between is limiting. Please see my post on how to get around this with an SSH tunnel.

Since I was using Zend Server in this example I have Z-Ray available, and while on a page I wished to debug I could simply click on the debug icon and select any of the debugging options.

Screenshot from 2016-04-03 15:24:13

This will cause Zend Debugger to contact Zend Studio for debugging, which in turn will ask the user if they wish to open the debugging perspective.

Screenshot from 2016-04-03 15:24:44

If Yes is selected the IDE is now ready to perform any debugging the user desires.

Screenshot from 2016-04-03 15:27:24

I hope this helps others. Happy debugging!!!

This post is one in a series on debugging. For others click below:

PhpStorm and debugging issue
Using an SSH tunnel to step debug through a firewall
Setting up local step debugging with PhpStorm

Zend Server and Sendmail failure bug

While trying to test the sendmail feature of Zend Server 6.3, on Ubuntu and CentOS, there was a bug.  I discovered that utilizing the Mail Preferences area of the Adminitration->Settings page and sending a test email to myself with the Sendmail option ended in an “Unknown error”.

The error returned by Zend Framework 2, which is used by Zend Server 6 was a generic error (Unknown error) if Sendmail returned an error status, but an empty error message.  Not much help, or was it?

Since the error appeared to be caused by Sendmail not returning a proper error the search for the issue led there.  See where my logic was going? My next step was to test sending an email with the PHP mail() function, and see if that shed any light on the issue.  Unfortunately it worked, which meant the issue was elsewhere.  But if the error wasn’t with PHP, Apache, Sendmail, Zend Server, or Zend Framework, where could it be?

At this point I enlisted one of my coworkers, Roman Basayev, who nailed it down.

Of course!  Zend Server on Linux installs Lighttpd for the Zend Server gui, and there must be a setting there for using Sendmail.  Sure enough in the file ‘/usr/local/zend/gui/lighttpd/etc/php-fcgi.ini’ there is a setting for ‘sendmail_path’ and it was empty.  So PHP running on Lighttpd was not able to find Sendmail, and therefore was not getting a decent error message.

The fix:

In the file ‘/usr/local/zend/gui/lighttpd/etc/php-fcgi.ini’ update the ‘sendmail_path’ to be ‘/usr/sbin/sendmail -ti’.  These are the paths on Ubuntu and CentOS, others may vary.

sendmail_path = "/usr/sbin/sendmail -ti"

After restarting Zend Server, all should be good  to go now.