Sticky Notes: Setting Up Zend Debugger

[rbzend]

The Sticky Notes Initiative has been created in order to cover the most popular Zend Studio features. Each feature will be discussed within a designated forum sticky topic, called a 'Sticky Notes topic'. Each 'Sticky Notes topic' will comprise a number of posts ('Sticky Notes'), explaining one of the aspects of the topic. The feedback on these is very welcome, as are suggestions of new 'Sticky Notes topics'. All forum participants that would like to share their knowledge in a certain area by starting and maintaining a 'Sticky Notes topic', or by contributing to an existing topic, are encouraged to do so.



These Sticky Notes will cover the installation of the Zend Debugger PHP extension in various operating systems. Zend Debugger is the PHP engine extension that can interrupt and influence script's execution, controlled from the front-end application - Zend Studio.

Table of Contents:

1. The Recommended Way - Zend Server
2. The Working Principles of Zend Debugger
3. Installing Zend Debugger on Linux
4. Installing Zend Debugger on Windows
5. Installing Zend Debugger on MacOS X
6. Installing Zend Debugger with XAMPP
7. Installing Zend Debugger with WAMP
8. Installing Zend Debugger with MAMP

You can post your feedback to Sticky Notes: Setting Up Zend Debugger here:
viewtopic.php?f=59&t=963

[rbzend]

The easiest way to get Remote Debugging to work is to install Zend Server. This also installs the Zend Debugger, saving you the trouble of reading the rest of this thread. Of course, this is not the only advantage of Zend Server. We have integrated Zend Studio 7 and Zend Server in a way that allows you to set up the debugging environment for your projects in no time. See this video for a demonstration – http://www.youtube.com/watch?v=yCrH1ukPUBw. And more integration is planned.
So, if you don't have a specific reason to use another PHP server stack, your best choice is Zend Server.

[rbzend]

To use debugging in the most effective way, it is important to understand how it works. In this Sticky Note I'm going to explain how a typical Remote Debugging session evolves. Local Debugging is not much different, basically just remove the web server from the picture.
The steps of a Remote Debugging session are shown in the picture below.
Click on the picture to see it without scroll bars:

debugging-2.png (87.59 KiB) Viewed 70072 times

Remote Debugging steps explanation:

1. A normal HTTP request is made. The request may be issued by Zend Studio itself, by the Zend Browser Toolbar or, in special cases, by an AJAX call, a Flex application or some other front-end application. In order to trigger a debug session this request must be made for a PHP file and contain certain GET or COOKIE parameters (see steps 2 and 3). For example:
   

   Code: Select all

   http://192.168.0.80/index.php?start_debug=1&debug_host=192.168.0.1&debug_port=10137

2. The web server decides that the request should be handled by PHP, according to the requested file's extension. However, firstly the web server will check whether the requested file exists on the server.
   The contents of the file itself do not really matter. Once the debug session is started, the contents can be transferred from the files in Zend Studio to the server. The same goes for included/required files – they can be fetched from Zend Studio during the debug session. And unlike the file that starts the debug session (index.php in the example image), they don't even have to exist on the server.
   At this point I want to mention the dummy.php file. This file should be accessible in the server's document root (e.g. http://your.server/dummy.php). It is used to trigger Zend Debugger when no specific file is going to be debugged. Examples of such actions are the Test Debugger button in Zend Studio and tunneling setup.
3. Zend Debugger is plugged into PHP's Zend Engine. When a request is received with the GET or COOKIE parameter start_debug=1, Zend Debugger interrupts the script execution.
4. Zend Debugger tries to establish a debug session with Zend Studio at the address defined by the debug_host and debug_port parameters. The first operation is evaluating the debug_host parameter against the zend_debugger.allow_hosts directive of the server's php.ini. If the test is successful, Zend Debugger creates a debug session with Zend Studio. Note there are many more GET parameters that affect the debug session creation and behavior, but the three above are obligatory.
5. The actual debug session uses a custom debug protocol. Note that in the debug session the client-server roles are inverted. Zend Debugger is the client and Zend Studio is the server. This is an important point to consider when configuring firewalls etc. By default, when trying to establish a debug session, Zend Debugger opens a random port on the server and connects to port 10137 on the Zend Studio workstation.
6. The script execution ends and the result of this execution is handed back to the web server.
7. The web server returns the script execution result in the HTTP response to the client that issued the HTTP request (see step 1).

[rbzend]

This Sticky Note explains how to set up Zend Debugger on Linux. The procedure applies to most distributions with PHP (and Apache) installed. For most steps you will probably need the superuser account.


1. Inspect the phpinfo() output of the server on which you want to install the Zend Debugger (or run php -i if you want to install Zend Debugger for the CLI version of PHP).
Click on the picture to see it without scroll bars:

phpinfo() after the installation

pre-a.png (130.04 KiB) Viewed 69826 times

You need the following information:
(1) The PHP version (PHP CLI - PHP Version => 5.2.9),
(2) The location of the php.ini file (PHP CLI - Loaded Configuration File => /etc/php5/cli/php.ini), or
(3) The additional .ini files directory (PHP CLI - Scan this dir for additional .ini files => /etc/php5/conf.d).
(V) Make sure that Thread Safety flag is disabled (PHP CLI - Thread Safety => disabled), there is no Thread Safe version of Zend Debugger for Linux.
(!) Note if you use the Zend Extension Manager (PHP CLI - with Zend Extension Manager v1.2.2, Copyright (c) 2003-2007, by Zend Technologies). The Zend Extension Manager can be installed as part of the Zend Optimizer installation.


2. Download Zend Debugger from the Zend Studio Downloads page. Select Studio Web Debugger and choose one of the Linux packages: 32-bit or 64-bit.
The following is a representation of the archive hierarchy (there is a Zend Debugger binary for all recent PHP versions):

Code: Select all

ZendDebugger-5.2.14-linux-glibc23-<architecture>/                                                   
    4_3_x_comp/
            ZendDebugger.so
    4_4_x_comp/
            ZendDebugger.so
    5_0_x_comp/
            ZendDebugger.so
    5_1_x_comp/
            ZendDebugger.so
    5_2_x_comp/
            ZendDebugger.so
    dummy.php
    md5                                               
    Inventory.xml                                     
    README

3. Create a new directory for Zend Debugger where it can be read by Apache (I will use /opt/Zend in this Sticky Note). In this directory create a sub-directory for your version of PHP – /opt/Zend/php-5.2.x (in my example PHP version is 5.2.9 – see screenshot (1)). The latter is obligatory if you use Zend Extension Manager, but won't hurt in other cases too.

Code: Select all

mkdir -p /opt/Zend/php-5.2.x

4. Unpack the relevant version of Zend Debugger into /opt/Zend/php-5.2.x:

Code: Select all

tar xf ZendDebugger-5.2.14-linux-glibc23-i386.tar.gz -C /opt/Zend/php-5.2.x --strip-components=2 --wildcards *5_2_x_comp*

Now the PHP configuration needs to be modified to load Zend Debugger. In most current Linux distributions, there is a php.ini file and a directory that contains more .ini files, each containing a piece of PHP configuration. I believe that creating a separate file for Zend Engine extensions is more convenient than modifying php.ini itself. Therefore, in my example I'll create a separate zend.ini file (you can name it differently). For most users this may have an additional advantage – while many distributions have separate php.ini files for the web server's PHP and PHP CLI, the configuration directory is the same for both. Thus, this zend.ini file will affect both PHPs.


5. Open the configuration file (php.ini or zend.ini) for editing. Here are the paths for some Linux distributions:
openSUSE:

- PHP (see screenshot (2)) – /etc/php5/apache2/php.ini
- PHP CLI – /etc/php5/cli/php.ini
- configuration directory (see screenshot (3)) – /etc/php5/conf.d

Ubuntu:

- PHP – /etc/php5/apache2/php.ini
- PHP CLI – /etc/php5/cli/php.ini
- configuration directory – /etc/php5/apache2/conf.d (actually a symlink to /etc/php5/conf.d)

Fedora:

- PHP and PHP CLI – /etc/php.ini
- configuration directory – /etc/php.d

6. Depending on whether you use Zend Extension Manager (see screenshot (!)), the following lines must be added to the configuration file.
Without Zend Extension Manager:

Code: Select all

# The section name is optional, but it's always a good idea to add it,
# especially if you are not using a separate file
[Zend]

# This directive needs the full path to the Zend Debugger binary
zend_extension =/opt/Zend/php-5.2.x/ZendDebugger.so


With Zend Extension Manager:

Code: Select all

# The section name is optional, but it's always a good idea to add it,
# especially if you are not using a separate file
[Zend]

# This directive instructs Zend Extension Manager to load Zend Debugger.
# Note that the path given is only the top of the hierarchy.
# Zend Extension Manager adds to this path the running PHP version
# in the form "/php-5.2.x/" and the name of the binary file "ZendDebugger.so".
zend_extension_manager.debug_server = /opt/Zend


7. An additional change needs to be made to allow Zend Studio to communicate with Zend Debugger. You need to specify your Zend Studio machine IP address (or network) in the allowed hosts list. Note that the network mask must be specified in CIDR notation, for example:
255.0.0.0 = /8
255.255.0.0 = /16
255.255.255.0 = /24
255.255.255.248 = /29
255.255.255.255 = /32 (exact match)

Code: Select all

# This directive allows Zend Debugger to start a debug session with:
# 127.0.0.1/32 – Zend Studio on the same computer
# 192.168.0.1/32 – Zend Studio on a computer with IP address 192.168.0.1
# 10.0.0.0/8 – Zend Studio on any computer with IP starting with 10.
zend_debugger.allow_hosts=127.0.0.1/32,192.168.0.1/32,10.0.0.0/8

# This directive allows Zend Debugger to expose itself
# upon request (this is used in some service functionality).
# The possible options are:
# never – do not expose (default)
# always – expose to whoever wants to know
# allowed_hosts – expose only if the request comes from an IP listed above
zend_debugger.expose_remotely=always


8. Save the configuration file and restart Apache.


9. Check the phpinfo() output and ensure the following:
- Zend Debugger is listed in the Zend Engine section.
- The Zend Debugger section exists.
- The values of zend_debugger.allow_hosts are correct.
- The value of zend_debugger.expose_remotely is correct.
Click on the picture to see it without scroll bars:

phpinfo() before the installation

res-a.png (85.76 KiB) Viewed 69810 times

10. Copy dummy.php from the downloaded Zend Debugger package to your server's document root. It should be accessible from a web browser as http://example.com/dummy.php (this script does not produce any output, but it should not result in the 404 error):
openSUSE:

Code: Select all

tar xf ZendDebugger-5.2.14-linux-glibc23-i386.tar.gz -C /srv/www/htdocs --strip-components=1 --wildcards *dummy.php

Ubuntu:

Code: Select all

tar xf ZendDebugger-5.2.14-linux-glibc23-i386.tar.gz -C /var/www --strip-components=1 --wildcards *dummy.php

Fedora:

Code: Select all

tar xf ZendDebugger-5.2.14-linux-glibc23-i386.tar.gz -C /var/www/html --strip-components=1 --wildcards *dummy.php

Known Issue

Zend Debugger may not load, crash or produce errors when used in conjunction with some other Zend Engine extensions. The most common examples are Zend Optimizer, Zend Loader, ionCube Loader and XDebug. For Zend Optimizer or Zend Loader it is recommended to use Zend Extension Manager, which will fix these compatibility issues. In case of ionCube Loader and XDebug make sure that Zend Debugger is loaded after these extensions. The loading order is defined by the order of corresponding directives in the configuration files. Therefore, the best approach is to add Zend Debugger directives at the very end of php.ini.

[rbzend]

This Sticky Note explains how to set up Zend Debugger on Windows. The procedure is based on the default PHP from php.net installation.


1. Inspect the phpinfo() output of the server on which you want to install the Zend Debugger (or run php -i if you want to install Zend Debugger for the CLI version of PHP).
Click on the picture to see it without scroll bars:

phpinfo() before the installation

pre-a.png (65.32 KiB) Viewed 69768 times

You need the following information:
(1) The PHP version (PHP CLI - PHP Version => 5.2.10).
(2) The location of the php.ini file (PHP CLI - Loaded Configuration File => C:\Program Files\PHP\php.ini).
(3) The Thread Safety flag (PHP CLI - Thread Safety => enabled).
(!) Note if you use the Zend Extension Manager (PHP CLI - with Zend Extension Manager v1.2.0, Copyright (c) 2003-2007, by Zend Technologies). The Zend Extension Manager can be installed as part of the Zend Optimizer installation.


2. Download Zend Debugger from the Zend Studio Downloads page. Select Studio Web Debugger and choose the Windows package.
The following is a representation of the archive hierarchy (there is a Zend Debugger DLL for all recent PHP versions):

Code: Select all

ZendDebugger-5.2.14RC9-cygwin_nt-i386\
    4_3_x_comp\
            ZendDebugger.dll
    4_4_x_comp\
            ZendDebugger.dll
    5_0_x_comp\
            ZendDebugger.dll
    5_1_x_comp\
            ZendDebugger.dll
    5_2_x_comp\
            ZendDebugger.dll
    5_2_x_nts_comp
            ZendDebugger.dll
    dummy.php
    Inventory.xml
    md5
    README.txt

3. Create a new directory for Zend Debugger. I will use C:\Program Files\PHP\Zend in this Sticky Note. In this directory create a sub-directory for your version of PHP – C:\Program Files\PHP\Zend\php-5.2.x (in my example PHP version is 5.2.10 – see screenshot (1)). The latter is obligatory if you use Zend Extension Manager, but won't hurt in other cases too.


4. Unpack the relevant version of Zend Debugger into C:\Program Files\PHP\Zend\php-5.2.x. Note, for PHP version 5.2.x we provide both the Thread-Safe version (directory 5_2_x_comp in the archive) and the Non-Thread-Safe version (directory 5_2_x_nts_comp in the archive).


5. Open the configuration file (in my example C:\Program Files\PHP\php.ini - see screenshot (2)) for editing.


6. Depending on whether you use Zend Extension Manager (see screenshot (!)), and have Thread Safety enabled (see screenshot (3)), the following lines must be added to the configuration file.
Without Zend Extension Manager and with Thread Safety disabled:

Code: Select all

; The section name is optional, but it's always a good idea to add it,
; especially if you are not using a separate file
[Zend]

; This directive needs the full path to the Zend Debugger DLL.
zend_extension="C:\Program Files\PHP\Zend\php-5.2.x\ZendDebugger.dll"


Without Zend Extension Manager and with Thread Safety enabled:

Code: Select all

; The section name is optional, but it's always a good idea to add it,
; especially if you are not using a separate file
[Zend]

; This directive needs the full path to the Zend Debugger DLL.
; The "_ts" suffix in the directive name suggests Thread-Safe mode.
zend_extension_ts="C:\Program Files\PHP\Zend\php-5.2.x\ZendDebugger.dll"


With Zend Extension Manager and with Thread Safety disabled:

Code: Select all

; The section name is optional, but it's always a good idea to add it,
; especially if you are not using a separate file
[Zend]

; This directive instructs Zend Extension Manager to load Zend Debugger.
; Note that the path given is only the top of the hierarchy.
; Zend Extension Manager adds to this path the running PHP version
; in the form "\php-5.2.x\" and the name of the DLL file "ZendDebugger.dll".
zend_extension_manager.debug_server="C:\Program Files\PHP\Zend"


With Zend Extension Manager and with Thread Safety enabled:

Code: Select all

; The section name is optional, but it's always a good idea to add it,
; especially if you are not using a separate file
[Zend]

; This directive instructs Zend Extension Manager to load Zend Debugger.
; Note that the path given is only the top of the hierarchy.
; Zend Extension Manager adds to this path the running PHP version
; in the form "\php-5.2.x\" and the name of the DLL file "ZendDebugger.dll".
; The "_ts" suffix in the directive name suggests Thread-Safe mode.
zend_extension_manager.debug_server_ts="C:\Program Files\PHP\Zend"


7. An additional change needs to be made to allow Zend Studio to communicate with Zend Debugger. You need to specify your Zend Studio machine IP address (or network) in the allowed hosts list. Note that the network mask must be specified in CIDR notation, for example:
255.0.0.0 = /8
255.255.0.0 = /16
255.255.255.0 = /24
255.255.255.248 = /29
255.255.255.255 = /32 (exact match)

Code: Select all

; This directive allows Zend Debugger to start a debug session with:
; 127.0.0.1/32 - Zend Studio on the same computer
; 192.168.0.1/32 - Zend Studio on a computer with IP address 192.168.0.1
; 10.0.0.0/8 - Zend Studio on any computer with IP starting with 10.
zend_debugger.allow_hosts=127.0.0.1/32,192.168.0.1/32,10.0.0.0/8

; This directive allows Zend Debugger to expose itself
; upon request (this is used in some service functionality).
; The possible options are:
; never - do not expose (default)
; always - expose to whoever wants to know
; allowed_hosts - expose only if the request comes from an IP listed above
zend_debugger.expose_remotely=always


8. Save the configuration file and restart the web server.


9. Check the phpinfo() output and ensure the following:
- Zend Debugger is listed in the Zend Engine section.
- The Zend Debugger section exists.
- The values of zend_debugger.allow_hosts are correct.
- The value of zend_debugger.expose_remotely is correct.
Click on the picture to see it without scroll bars:

phpinfo() after the installation

res-a.png (48.7 KiB) Viewed 69785 times

10. Copy dummy.php from the downloaded Zend Debugger package to your web server's document root. It should be accessible from a web browser as http://example.com/dummy.php (this script does not produce any output, but it should not result in the 404 error).


Known Issue

Zend Debugger may not load, crash or produce errors when used in conjunction with some other Zend Engine extensions. The most common examples are Zend Optimizer, Zend Loader, ionCube Loader and XDebug. For Zend Optimizer or Zend Loader it is recommended to use Zend Extension Manager, which will fix these compatibility issues. In case of ionCube Loader and XDebug make sure that Zend Debugger is loaded after these extensions. The loading order is defined by the order of corresponding directives in the configuration files. Therefore, the best approach is to add Zend Debugger directives at the very end of php.ini.