Remote Debugging Over Built-in "Tunnel" in Zend Studio v7.2

The goal here is to setup remote debugging on an AWS EC2 instance or any other machine which restricts outgoing ports using Zend Studio's tunneling option.  I set this up on v7.2  It's likely similar on the newer versions as well but could vary because Zend loves to move configuration settings around between versions.

This does not use SSH tunneling.  It tunnels the data back out over port 80.  So it does not require much of any sort of access to the web server once you get the web server configured (or if you build the configuration into your deployment scripts).  I had a hard time getting this working.  This is because of the allow_hosts and allow_tunneling configuration.  So pay special attention to getting that configured right.

Also, the tunnel connection seems to time out occasionally even though it shows it as still connected.  So if your debug session suddenly won't work, try resetting it. I also have to say this runs painfully slow, but it's better than nothing.  I need to open up the remote ports and get an apples to apples speed comparison.  Maybe remote debugging is just inherently slow.  Local debug definitely runs substantially, maybe 4x or 5x faster than this.

CONFIGURE THE TUNNEL SERVER IN ZEND STUDIO

Click "Zend Studio" in the menu bar and select "Preferences"

Go to the PHP section and expand it.  Look for PHP Servers and select it.

This brings up a dialog box with a couple menu buttons on the right side.  Select "New".

Give the server a name "NewServerName" and a URL (http://test-server)

Click "Next"

Setup the server path mapping:

Path on Server:

/site/current

Path in Workspace:

/ExchangeISIS

Click Next

I'm not running Zend Server so I did not select Zend Server Integration.  

So just click Next

Now we finally come to the Tunneling Settings screen

Tick the check box for "Enable Tunneling"

Click "Finish" to complete setup

Hit OK to get out of the preferences Dialog box

CONFIGURE THE SERVER

Now you have to setup the server to actually support debugging assuming you don't already have it in the image which you probably don't or you wouldn't be reading this right now.

SO: You need to download the debug DLL extensions from Zend Studio at:

http://www.zend.com/en/products/studio/downloads

If you are not sure what version of Linux you are running on the server do a:

file /sbin/init

This will produce something like:

/sbin/init: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), ...

or

/sbin/init: ELF 32-bit LSB shared object, Intel 80386, version 1 (SYSV), ...

 and obviously, if it says 32, then you are running a 32 bit OS so get the 32 bit version of the 

At this point, you have to register with Zend to complete the download (annoying, yes I know):

Note that the download page has tabs on it, and it will default to the OS you are running.  But that's probably not the OS you want to run it on.  So make sure you get the correct file.  I got an ELF error the first time I tried to run this (visible in the /var/logs/apache2/error.log".  I did a "file ZendDebugger.so", and it said "Mach-O" something or other.  That's a MAC format...because my work development machine is a MAC.  Oops.

Upload the file to the server.  Gunzip it.  tar -xvf the tar file.  This should produce a directory similar to:

ZendDebugger-20110410-linux-glibc23-i386

Navigate into this directory.  You will see multiple directories named for various PHP versions, a README.txt and a dummy.php file in this directory.

Select the proper PHP file  

Do a "php -v" from the command line on the remote server.

This will tell you what version of PHP you are running.  Select the appropriate Zend Debugger version.

In my case, I got:

PHP 5.3.2

So I took the ZendDebugger.so from the "5_3_x_comp" directory.

Move the file to a suitable location

I usually use: /usr/local/lib/zend (I have to create the zend directory)

If you don't know where the php.ini file is on the system in question, you can use phpinfo (detailed below) to find it.  I got smart here and initially did a: php -i | grep php.ini and got an /etc/php5/cli/php.ini  (uh...NO!  Note the CLI?)  This is the php.ini for php invoked from the command line interface.  It's not the same as when invoked from the debugger.  My actual one is in /etc/php5/apache2/php.ini.  If you can't find it, look at the top of the phpinfo output and note the location for "Loaded Configuration File".  Take note of the extensions directory which is, in this case, /etc/php5/apache2/conf.d.  

Go to the extension directory and create a new file named zend.ini (should be a couple other *.ini files in this directory already).  Whenever php starts up, it searches this directory and pulls in all the .ini files.  Now alter the contents of zend.ini to point to the "ZendDebugger.so" file with the following:

zend_extension=/usr/local/lib/zend/ZendDebugger.so

zend_debugger.allow_hosts=67.164.28.0/24, 127.0.0.1

zend_debugger.allow_tunnel=67.164.28.0/24, 127.0.0.1

zend_debugger.expose_remotely=always

Of course your IP addresses will be different, but you need both your ISP address as well as the 127.0.0.1 address.  This gave me a headache trying to figure out how to get it to work.

Note that "67.164.28.0/24" should be replaced with your external IP as the ISP has assigned it to you and Zend expects it in CDIR format.  Google "what is my ip address" to find out what it is.  Let's say it's 69.127.36.13.  You could write this as:

zend_debugger.allow_hosts=69.127.36.0/24, and any IP address with 67.127.36.0 to 69.127.36.255 will match it.

Copy the dummy.php file which is in the root directory where you untarred the ZendDebugger file to the document root of your server (probably something/something/public)

Save the settings and restart your web server:

"apache2ctl restart" or whatever that command happens to be on your server

Go to the document root of the web server (where you index.php file reside).

Create a new file named "phpinfo.php"

Edit it and add this single line at the top:

<?php phpinfo(); ?>

Go to  a web browser and access this file.  If you can't access, and you don't have it intentionally blocked via .htaccess, that's a separate problem.  Get your web server working to the point it can at least serve a page.

Assuming you can access it, you will (should) get a page full of information about your PHP installation with each function in a separate section.  Scroll to the bottom and find the "Zend Debugger" section.  If it's not in there, then you don't have ZendDebugger setup properly in the "php.ini" file, so at least get this working before trying to proceed.

You can also check the apache2 error log (or whatever server log you are using).  On ubuntu, the apache log file is located in /var/log/apache2/error.log.  

There is a good discussion of how to get this working at: http://forums.zend.com/viewtopic.php?f=59&t=962#p4190 which I got benefit from and I hope you do as well should you need it.

CONFIGURE ZEND STUDIO

Go to Zend Studio | Preferences | PHP | Debug | Installed Debuggers and select "Zend Debugger" and press the "Configure" button.  The default port for this is 10137, which is fine.  Set the Client Host IP to 127.0.0.1.  Make sure the Dummy File Name is still "dummy.php"

Now, enable the tunneling by activating the tunnel from the menu bar.  Here I had to attach a screenshot as there's no good way to describe this. 

Now go to Run | Debug Configurations.  Select PHP Web page, right click and create a "new" entry.  Set the PHP server to your newly created server: "NewServerName" i.e. whatever you named it when you created it above.  Pick the starting file from your project, and enter the matching URL (assuming auto generate didn't work correctly which it never does for me).

Now hit the "Test Debugger" button.  You should get success.  If you didn't, then check your "allowed hosts" again and go back over the steps.  

I verified that this setup is definitely working on my remote AWS EC2 development server.  When I get time, I am going to get NetOps to open the required ports or cede their tightfisted control so I can test non-tunneled remote debugging on the same machine.  But that's a task for another day.