Debugging TYPO3 Flow

I’ve finally figured out how to debug TYPO3 Flow using NetBeans; including support for breakpoints in your class files. This is also relevant for other IDEs.

For NetBeans, a step-by-step tutorial is provided which works fine on my mac:

1. Prerequisites: xdebug

First, xdebug needs to be installed and configured to enable debugging. Add the following to your php.ini:

[xdebug]
xdebug.remote_enable = on
xdebug.remote_host = localhost
xdebug.remote_port = 9000

2. Install Debugger-Proxy

Now, FLOW3 implements very easy Dependency Injection and AOP features. For them to work, it needs to do some PHP class magic: It renames most of your original classes to OrignalClassName_Original, and automatically generates a new class without the _Original suffix which implements all the magic.

While this is nice and shiny, it makes debugging cumbersome: If you add a breakpoint to your normal code, it never gets executed as the class is copied to another location.

In order to solve this problem, meet the debugproxy. It sits between your IDE and xdebug and re-writes breakpoints and other class directories. It has been originally created by Iván Montes, but I’ve customized quite heavily towards FLOW3. Let’s download it:

git clone https://github.com/sandstorm/debugproxy.git

To run it, just call:

php debugproxy.php -f -c Development

This starts the proxy such that it works for the FLOW3 Development context. For debugging Functional Tests, use Testing there.

Now, you only need to tell your IDE to connect to xdebug using port 9010.

3. Adjust FLOW3

Currently, you still need a FLOW3 changeset, which at least I need for debugging to work flawlessly: https://review.typo3.org/#/c/13540/

4. Setting Up NetBeans

I set up NetBeans 7.2 in the following way:

Preferences -> PHP -> Debugging

• Debugger Port: 9010
  
• Session ID: netbeans-xdebug
  
• Stop at first line: NO
  
• Watches and Balloon Evaluation: YES
  

5. Debugging a web request

To debug a web request, start the debug proxy (or just leave it running):

php debugproxy.php -f -c Development

Then, set a breakpoint in NetBeans and start debugging using Debug -> Debug Project.

Now, call a website you want to debug, and modify the URI in your browser such that it includes XDEBUG_SESSION_START=netbeans-xdebug as GET parameter. You should see your breakpoints kicking in. Enjoy!

6. Debugging a Functional Test or a Unit Test

On the command line, run the following line to set the IDE key:

export XDEBUG_CONFIG="idekey=netbeans-xdebug"

Then, start the debug proxy in Testing context and debug as usual:

php debugproxy.php -f -c Testing

Closing Notes

You might experience some problems when trying to debug while the code caches are still empty — it should work in most cases, but might not work in all. So keep that in mind, and just debug your second request.

Happy Debugging,
Sebastian