Debugging PHP CLI Scripts

Overview

This article explains how to use the Server Debugger to debug command line PHP scripts without a dedicated web server.
Normally you do not need to perform these activities on local PHP, since Zend Studio for Eclipse can be configured to load any PHP binary and configuration to debug your scripts on, assuming the Zend Debugger extension is loaded in that PHP configuration.

Instructions

PHP CLI configuration

  1. Make sure you have Zend's extensions installed, especially the debugger extension
    For reference, take a peak at the Web Server's php.ini file for the directives that load Zend's extensions.
    You might also like to download the Zend Debugger standalone package from the Zend Studio downloads page and read the manual installation instructions.
  2. Configure in the php-cli' php.ini file to allow the client machine, upon which the Studio client is running, to perform debugging. Edit "zend_debugger.allow_hosts" and add the IP address of the Studio client machine (e.g.: zend_debugger.allow_hosts=127.0.0.1/32,10.1.2.17/32).

Setting Environment variables to act as Request parameters

Note:
This example was tested on Linux.

1. On the server machine, set the environment variable QUERY_STRING in the manner described below:

start_debug=1&debug_host=[host name or IP of the Studio Client machine]&debug_port=[the port that is configured in your Studio Client settings]&debug_stop=1 .

Note about local file
If you want the debugged script to be a local file, add the following string to the environment variable: "&no_remote=1"

External links to setting Environment variables are at the end of this article

2. Make sure to fill the appropriate host name and port number above, according to the settings of the Studio client

Check the Studio client's preferences "Debug" tab for the "port" parameter

Zend Studio Client configuration

The following is not mandatory in some cases

  1. In Studio 5.x, go to Preferences -> Debug -> Debug Server URL. Use the server IP to point to the machine where PHP CLI will be running
  2. If you want to just debug a php script that reside on the local machine, where Studio client is running, either open the file in the editor or make sure it is included in the currently opened project.

Starting a Debug session from PHP CLI

On the server machine, run the php-cli parser with the script you want to debug as a parameter.
Make sure to set up the environment variable before as shown above.
This is done most conveniently in the following example:

QUERY_STRING="start_debug=1&debug_host=10.1.1.17&no_remote=1&debug_port=10000&debug_stop=1" /usr/local/bin/php /var/www/test.php

Comments:

  • The command should be typed in one line, otherwise the QUERY_STRING environment variable will not affect php.

  • The php parser location and the debug_host parameters above would probably be different.

  • This will initiate a debug session on the Studio Client. Continue debugging as usual from here.

Note about Zend Studio for Eclipse:
When you set a script to be debugged by Zend Studio for Eclipse, you need to change the QUERY_STRING

QUERY_STRING="start_debug=1&debug_host=10.1.1.17&no_remote=1&debug_port=10137&debug_stop=1&debug_session_id=1002"

Breakdown of the above Query String for Zend Studio for Eclipse:

debug_port:
In Zend Studio for Eclipse the default port is 10137

debug_session_id
This is a random number but in case of setting several places to initiate debug sessions, use a different number for each location.
You can also generate a random number when possible.

Result

Running the PHP-CLI with debug parameters as shown above should initiate a new Debug session in your Zend Studio client, with remote or local file as source for breakpoints.