PHP PORTABLE IDE: Notepad++ XDebug 1

From The Uniform Server Wiki
Jump to navigation Jump to search


MPG UniCenter

Uniform Server Portable PHP IDE.

Notepad++ XDebug

Our portable PHP IDE is currently lacking debugging capabilities. This page addresses that by providing a step-by-step guide for installing and setting up XDebug and Notepad++. It covers only PHP CLI debugging if you are looking for server-side PHP debugging check out page XDebug 2.

One of the advantages of running PHP in command line mode is that it does not require a server such as Apache for executing PHP scripts.

The guide is split across two pages; first covers installation while second provides basic CLI debugging techniques using Notepad++ DBGP Plugin (already installed).


Debugging a PHP CLI script requires control of the PHP interpreter and a mechanism to separate script flow and error messages generated. A debugging client must provide unobtrusive communication with the interpreter while allowing a script to run.

The PHP extension php_xdebug.dll seamlessly installs code to provide interpreter control and communication between a client (Notepad++ with DBGp plugin installed) and the PHP interpreter over port 9000. Effectively php_xdebug.dll includes a mini server to provide communication with a client.

Sequence of events

  • Step A) Run Notepad++.
  • Step B) Start Notepad++'s client (DBGp plugin) this opens socket 9000
    (listens on port 9000)
  • Step C) Run script from Notepad++ (Executes PHP interpreter).
  • Step D) Interpreter loads configuration file and loads extensions (php_xdebug.dll)

  • Step E) XDebug establishes contact with client.
  • Step F) Script is loaded and run.
  • Step G) Script execution (debugging) is controlled by client.

Note 1: Debugging is initiated as soon as the interpreter loads XDebug.

Note 2: If the script is initiated from an external source (for example a batch file) XDebug determines if the script (F) is displayed in Notepad++ if not downloads it.

Note 3: If XDebug starts debugging a new page that page is download if not already displayed in Notepad++.

Ide xdebug 1.gif


XDebug download and install

Xdebug is the extension for PHP that helps debugging PHP scripts by providing debug information for details see XDebug website.

Windows binaries are located on this download page

Although our IDE uses VC9 thread-safe binaries its worth downloading both VC6 and VC9 binaries.


Install 5.3 VC9 (32 bit) binaries to our IDE

  • Copy file C:\us_portable_ide_temp\php_xdebug-2.1.0-5.3-vc9.dll
  • To folder C:\us_portable_ide\unicode\php\extensions


PHP Configuration file

Our IDE for debugging will use a separate PHP configuration file.


Create a new file php_cli_ide_debug.ini with the following content and save to folder C:\us_portable_ide\unicode\php


extension_dir = "./extensions"
;error_reporting = E_ALL | E_STRICT
error_reporting = E_ALL 
date.timezone = "Europe/London"
short_open_tag = Off

  • Section [xdebug] loads and configures XDebug
  • Line: zend_extension=./extensions/php_xdebug-2.1.0-5.3-vc9.dll
    Loads the XDebug extension
  • Remaining lines configure XDebug to run automatically when a script is run.
  • Some lines set default values hence are not required. However leaving them in-place does no harm and makes it slightly clearer as to what is set and for what reason.

Section [xdebug] parameters


Default value: 0 (off) Normally you need to use a specific HTTP GET/POST variable to start remote debugging. When this setting is set to 1 (on), Xdebug will always attempt to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE variable was not present.


Default value: 0 (off) This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.


Default value: localhost Selects the host where the debug client is running. Use a host name or an IP address. This setting is ignored if xdebug.remote_connect_back is enabled.


Default value: 9000 The port to which Xdebug tries to connect on the remote host. Port 9000 is the default. Many clients use this port number, it is best to leave this setting unchanged.


Default value: dbgp The DBGp protocol is supported by Notepad++ client.


Default value: req Xdebug will try to connect to the debug client as soon as the script starts.


Default value: *complex* Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last USERNAME. The default is set to the first environment variable that is found. If none could be found the setting has as default .


The following function is useful for debugging

  • xdebug_break() it emits a break-point to the debug client.

Add the function to your script it makes the debugger break on the specific line as if a normal file/line break-point was set on this line. This function is covered on next page.


Notepad++ DBGp client configuration

Configuring the DBGp client is straight forward. Steps shown below:

  • Open DBGp configuration window Plugins>DBGp>Config...
  • Step A) Check Bypass all mapping (Local windows setup)
  • Step B) Check Refresh local context on every step
  • Step C) Check Refresh global context on every step
  • Step D) Check Break at first line when debugging starts
  • Step E) Click OK

Note 1:

We are running all our applications (Notepad++ PHP CLI Uniform Server) on the same system (will not be debugging remotely, over a network) hence at step A) check Bypass all mapping (local windows setup) box.

Note 2:

Step D) Break at first line when debugging starts is optional. If unchecked you must manually set at least one break point in your script.

Ide xdebug 1a.gif


Docking Problem

There is a minor problem when opening both console and debugging windows. These are initially docked and overlap each other preventing access to tabs on the debugging window.


  • Start Notpad++
  • Step A) Click reduce size and resize application window so it fills top half of screen.

  • Step B) Click Debugger Opens debug window.
  • Step C) Left click on title bar (blue bar), keep mouse key pressed and drag away from Notepad++ edit window. Resize debug window as appropriate.

  • Step D) Click Show Console Dialog opens console widow.
  • Step E) Left click on title bar, keep mouse key pressed and drag away from Notepad++ edit window. Resize console window as appropriate.


Closing Notepadd++ saves these new windows positions. Next time Notepad++ is run console and debugging widows remain un-docked.

Ide xdebug 1b.gif


Test Configuration


Into a console window type the following: $(NPP_DIRECTORY)\php\php.exe -c $(NPP_DIRECTORY)\php\php_cli_ide_debug.ini -v

Check Xdebug has been loaded. Result similar to the following:

$(NPP_DIRECTORY)\php\php.exe -c $(NPP_DIRECTORY)\php\php_cli_ide_debug.ini -v
C:\us_portable_ide\unicode\php\php.exe -c C:\us_portable_ide\unicode\php\php_cli_ide_debug.ini -v
Process started >>>
PHP 5.3.3 (cli) (built: Jul 21 2010 20:28:30) 
Copyright (c) 1997-2010 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies
    with Xdebug v2.1.0, Copyright (c) 2002-2010, by Derick Rethans <----- Confirms Xdebug loaded
<<< Process finished.
================ READY ================


New NppExec script

For a quick refresher view the following Add new NppExec command script

Add new NppExec command script

Add the new script as follows:

Add new command script

  • Press key F6
  • Step A) From drop-down menu select <temporary script>
  • Step B) Enter list of commands as shown below
$(NPP_DIRECTORY)\php\php.exe -c $(NPP_DIRECTORY)\php\php_cli_ide_debug.ini $(FULL_CURRENT_PATH)

  • Step C) Click save button

Opens Script name side window:

  • Step D) Enter a name for command script run_php_cli_debug
  • Step E) Click save
  • Click OK - Saves and runs script.


With no script open following message is produced

C:\us_portable_ide\unicode\php\php.exe -c C:\us_portable_ide\unicode\php\php_cli_ide_debug.ini new  1
Process started >>>
Could not open input file: new
<<< Process finished.
================ READY ================


Assign command script to menu items

The following assigns our command script to menu items.

  • Open NppExec Advanced Options Plugins>NppExec>Advanced Options..
  • Step E) Check box Place to the Macro submenu
  • Step F) From the drop-down menu select command script run_php_cli_debug
  • Step G) Enter Item name Run PHP CLI Debug
  • Step H) Click Add/Modify Menu Items are automatically inserted.
  • Step I) Click OK and Restart Notepad++.

Note 1: Check new menu items added to macro drop-down menu as shown below.

The above allows you to perform debugging on a CLI script displayed in Notepad++.



Above has shown how to configure our PHP IDE for debugging CLI scripts.

Debugging PHP CLI scripts is relatively easy or should I say the actual steps are see next page for details!