Remote Debugging and Breakpoints


Applies To:

[ Zend Studio ]
[ All operating systems ]


One of the most common remote debugging scenarios for a PHP developer using Zend Studio is this:

  1. Opening the source code.
  2. Setting the breakpoints in the relevant project.
  3. Running a debug session.
  4. Following the execution of the application by monitoring/controlling the run-time environment at breakpoints.

The default settings of all Zend components involved in remote debugging are good for most cases and should enable the scenario outlined above. However, some developers notice that Zend Studio doesn't hit pre-set breakpoints under certain circumstances. In 99.9% of cases there is no bug involved in this problem. As a rule, the problem is the incorrect configuration and usage. This article's aim is to describe the remote debugging principles of working, and to list the requirements for making the pre-set breakpoints work.


Remote debugging can be launched in three ways:

  1. From within Zend Studio, using the Debug URL functionality (Run | Debug URL).
  2. From Internet Explorer or Firefox, using the Zend Browser Toolbar.
  3. From within Zend Studio, using the Debug As Web Page functionality (Run | Debug As | PHP Web Page).

In the first case, Debug URL, the breakpoints pre-set in the project files will not work. This functionality does not support the usage scenario in question by design. Therefore, if this is your preferred method of launching a debug session, you probably should consider a different approach.

The ultimate condition for making a remote debugging session to stop on breakpoints pre-defined an a Zend Studio project, is instructing Zend Debugger to fetch files from Zend Studio and execute them instead of the corresponding files that reside on the server. This is done by marking the relevant options in either the Zend Browser Toolbar settings or in the debug launch configuration of Zend Studio (see the next two sections). Without these instructions Zend Debugger executes files from the server; These files have no breakpoint information. The breakpoint information is stored in Zend Studio workspace for the files that belong to PHP Projects. Therefore, if Zend Debugger executes a file that is not part of a Zend Studio project, no breakpoints apply.

Zend Browser Toolbar Settings

In Zend Browser Toolbar go to Extra Stuff | Settings and ensure that Debug Local Copy is marked:


Zend Studio Debug Configuration Settings

In Zend Studio go to Run | Debug Configurations, select your launch and verify that the Local copy if available option is selected on the Advanced tab:


How This Works

In the case that remote debugging works in general, but the execution doesn't stop at breakpoints, read this section. It provides a description of the processes involved in a debug session, which will help you to understand where the problem may be in your case. Here are the stages of a typical debug session:

  1. Zend Browser Toolbar or Zend Studio issues a regular HTTP request to the server; The request target is a PHP file (for example - http://localhost/index.php). Part of the request are GET or COOKIE parameters that trigger the debug session and communicate its settings. For example:

    For detailed description of GET/COOKIE parameters, see "Zend Debugger GET Request Parameters".
  2. The web server (Apache or IIS) receives the request and invokes PHP.
The requested file must exist on the server, otherwise the web server will just return HTTP error 404.
  1. Zend Debugger is installed on the server and hooked into PHP's Zend Engine. Upon detection of relevant GET or COOKIE parameters (mainly, start_debug), Zend Debugger intercepts the script execution.
  2. Zend Debugger "rings back" to Zend Studio on the IP address and TCP port given in GET/COOKIE parameters (debug_host and debug_port) and asks to start a debug session.
  3. A debug session is started and the communication between Zend Debugger and Zend Studio is established. The communication between Zend Debugger and Zend Studio uses a special debugging protocol. According to standard client-server definition, in this communication Zend Studio is the server and Zend Debugger is the client.
  4. From GET or COOKIE parameters Zend Debugger reads the instruction to use files from a project, rather than the ones on the server. The parameter in question is use_remote and needs to be set - "use_remote=1". Additionally, the parameter no_remote can be used - "no_remote=0".
The parameter names may be confusing. However, the "_remote" part of the parameter name refers to Zend Debugger. From its point of view the files in the Zend Studio project are remote.
  1. Zend Debugger requests the file to debug from Zend Studio, providing the server name and the physical path of the file on the server.
  2. Zend Studio tries to look up the file in one of the projects. This process involves Path Mapping.
    Path Mapping is used to map a physical path on a specific server to a virtual path in Zend Studio project. This allows avoiding selection of a wrong file in the case that a file with the same name exists in more than one project or in several sub-directories of the same project.


While the physical path of the file is provided by the web server, the server name is taken from the original_url GET parameter of the request.

For more information about Path Mapping and its configuration, visit the documentation site Path Mapping.

  1. If Zend Studio finds the file, it sends the file to the server via the debug protocol. It also sends the associated breakpoint information for this file.
  2. Upon reception of the file, Zend Debugger executes it instead of the file from the server and pauses the execution at breakpoints.
  3. At the end of the debug session, Zend Debugger returns command to PHP's Zend Engine, PHP returns the execution result to the web server and the web server sends the HTTP response to the original client - Zend Studio or the web browser.

Excerpt: This article's aim is to describe the remote debugging principles of working, and to list the requirements for making the pre-set breakpoints work. This article also explains the remote debugging session flow and the concept of breakpoints and Path Mapping.

Original Post Date: 2013-03-25 16:20:59

External Links:

Zend Studio Documentation - "Debugging a PHP Web Page"
Zend Studio Documentation - "Debugging Using the Zend Browser Toolbar"
Zend Studio Documentation - "Path Mapping"

Alternative Description:

This article explains the remote debugging session flow and the concept of breakpoints and Path Mapping.

Tags: Apple OS X 10.7 (Lion),Apple OS X 10.8 (Mountain Lion),Apple OS X 10.9 (Mavericks),breakpoint,COOKIE,Debian / Ubuntu,debug_host,debug_port,GET,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,original_url,path mapping,RedHat Enterprise Linux / CentOS,remote debugging,SUSE Linux Enterprise Server / OpenSUSE,use_remote,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,attachment