Basic PHP Debugging

From Aptana

These are the basic instructions for starting a debug session.

There two types of debugging

  • internal debugging (e.g. Script debug)
  • Web Page debug, which uses a debugger extension (either Zend or XDebug) installed on a server


The Debugger

The Studio debugger works with the Zend and XDebug extensions, and they can be controlled through a Preference:

  • Windows -> Preferences -> Aptana -> Editors -> PHP -> Debug -> PHP Interpreters, and then edit the default interpreter.

This dialog displays the installed interpreters that are used for PHP Script debugging, internal Previewing, Smarty code validation and PHPDoc generation. When you click to edit a built-in interpreter, you will notice the php.ini editor that will allow you to perform several actions:

  • Add/remove an entry
  • Add/remove a section
  • Comment an entry
  • Validate the settings


A little bit on the validation process:
When you hit the Validate button, the PHP interpreter will try to execute with the current php.ini settings and collect the errors/warnings.
This validation can be used to determine which of the extensions triggered warnings, or even, triggered fatal errors and could not be loaded. At the end of the validation, the question marks next to the extensions will be replaced with appropriate icons (Error, Warning or Ok).
Hovering over the extension line will display the error/warning message that the PHP process output when it was validating. In general, any fatal extension should be commented out to allow the PHP process function currently.

Note - This process is no a "100% bullet-proof", and in some cases where the PHP process fails to load a deeper investigation might be needed to determine the cause.

The default interpreters that we bundle contains a pre-configured XDebug extension; to use Zend you have to manually add it to that dialog and then select Zend as Debugger Type.

Script debug sessions

These can be initiated in a several different ways.


  1. Right click the editor area and select 'Debug As'->'PHP Script'.
  2. You will be prompted to move to the debug perspective - Click yes.
  3. In that perspective you will see the debug stack, variables and breakpoints views. You can also add more views, like the Expressions view to track any Watch expressions you add.
  4. From here you can do a step into, step over and step return by clicking the buttons on the stack view or by using F5/F6/F7 keys.
  5. You can set more breakpoints as you debug, or even run to a line that you mark (right-click + 'Run to line' action, or Ctrl+R).

The second way you can run a script (the one currently active in your editor):

  • Click the bug-shaped button on the application toolbar.
  • Hit the 'arrow' to select PHP CGI or PHP CLI execution.

The third way is to hit the same debug arrow as above and select Open debug dialog. A dialog will be opened, in which you can create new PHP Script debug configurations and then launch them.

PHP Web page debug configuration

This can be setup only through the debug dialog.

Open the dialog and add a new configuration for a "PHP Web Page".

To complete such a configuration you have to set up a server (such as Apache, Generic or XAMPP) through the launch configuration dialog, or through the Servers view.

  • Select the server that you are debugging against
  • Select the type of debugger that is installed on the server side (XDebug / Zend Debugger)
  • Select the initial PHP script that will be the entry point for the debug session
  • Verify that the Auto Generated URL matches a valid URL on your server. In case it does not match, un-check the Auto Generate option and edit the path.
  • Hit the Debug button.

Please follow Remote_PHP_Debugging for more detailed information about the remote debugging.


Debug Ports

There are two debug port that the studio opens when loading.
Port 9000 for the XDebug debugger and port 10000 for the Zend debugger.
These ports can be controlled through a Preference:

  • Windows -> Preferences -> Aptana -> Editors -> PHP -> Debug

When launching a PHP Script, the Studio will inform you in case that the port it's listening to does not match the XDebug port that was defined in the php.ini.
For example, if the php.ini indicates that the XDebug debugger should contact port 9001, while the Studio listens on port 9000, a message box will indicate the problem and will direct you to change the listen port or the ini setting.


XDebug Configurations

The Studio debugger bundles a XDebug debugger with a pre-configured php.ini. However, if you wish to define your own XDebug setting you'll have to make sure that the minimal required settings for a session initialization are set in your ini.

zend_extension_ts=<debugger path>/


  • Port 9000 is the default port for XDebug. In case the Aptana PHP debugger client is set to listed on port 9000, there is no real need to set it in the ini, however it's a good practice to do so.
  • In case that an XDebug session is triggered from the studio and the client port does not match the debug port defined in the ini, the Studio will prompt you about it and advise you what to do (see above).
  • The zend_extension_ts is only valid in cases where the PHP interpreter was compiled as 'Thread-Safe'. In cases where it was not compiled as such (and you have a compatible xdebug extension), the line should be zend_extension=<debugger path>/ (or similar).