Debugging PHP CLI Scripts


Applies To:

[ Zend Studio 5.x, Zend Studio for Eclipse 6.x, Zend Debugger ]
[ All operating systems ]


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.


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=,

Setting Environment variables to act as Request parameters

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=" /usr/local/bin/php /var/www/test.php


  • 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


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

In Zend Studio for Eclipse the default port is 10137

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.


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.


Excerpt: This article explains how to use the Zend Debugger to debug command line PHP scripts without a dedicated web server, i.e. how to start a debug session from the command line.

Original Post Date: 2009-04-13 12:10:50

External Links:

Windows Environment Variables
Linux Environment Variables

Alternative Description:

How to debug PHP script running in CLI / CGI using Zend Studio

Tags: Apple OS X 10.7 (Lion),Apple OS X 10.8 (Mountain Lion),Apple OS X 10.9 (Mavericks),cli,Debian / Ubuntu,debug,MacOS 10.6 and earlier,MS Windows 2003 Server,MS Windows 2008 Server,MS Windows 2012 Server,MS Windows 7,MS Windows 8,MS Windows XP,no_remote,QUERY_STRING,RedHat Enterprise Linux / CentOS,studio,SUSE Linux Enterprise Server / OpenSUSE,ZDE 5.x and older,Zend Studio 10.x,Zend Studio 11.x,Zend Studio 7.x,Zend Studio 8.x,Zend Studio 9.x,Zend Studio for Eclipse 6.x,oldKB