Derick Rethans - tag: xdebug

Multiple PHP versions set-up

Mon, 07 Nov 2011 09:11:00 +0000

Multiple PHP versions set-up

Monday, November 7th 2011, 09:11 GMT

For many of my projects (both hobby and commercial) I need to support many different PHP configurations. Not only just different PHP versions, but also debug builds, ZTS builds and 32-bit builds. In order to be able to test and build extensions against all those different PHP configurations I have adopted a simple method that I'm sharing with you here.

The major part of it is that I use a different installation prefix for every configuration of PHP that I make. Right now, ls /usr/local/php shows:

5.1dev  5.3.2  5.3.8dev  5.3dev-32bit    5.3dev-zts  5.4dev      trunk
5.2dev  5.3.7  5.3dev    5.3dev-nodebug  5.4.0beta1  5.4dev-zts

There are two types of PHP installs that I make: "dev" versions from SVN branches, and "release" versions build from SVN tags. From the list above you see I have the SVN versions of 5.1, 5.2, 5.3.8, 5.3 (in various forms) and 5.4 (both normal, and ZTS).

I have a script to compile PHP which whatever combination I want: version, debug (default) or non-debug, normal (default) or ZTS; and 64-bit (default) or 32-bit. The configure options are nicely hardcoded :-)

The scripts accept arguments in a specific order:

version ["debug"|"nodebug" [, "no-zts"|"zts" [, ""|"32bit" ] ] ]

For a simple 5.3dev build I run:

./build 5.3dev

This compiles PHP 5.3 from SVN, in debug mode, without ZTS and for the 64-bit architecture. Something more exotic variants could be:

./build 5.3.8 debug zts
./build 5.4dev nodebug no-zts 32bit

Each invocation of the script will configure and build PHP, and then install into /usr/local/php/{{variant}}.

The script also has a hard coded location where the PHP sources are. In my case, that's a sparse checkout into /home/derick/dev/php/php-src.

With the help of a small .bashrc snippet:

function pe () {
        version=$1
        shift

        if [ "$#" == "0" ]; then
                export PATH=/usr/local/php/${version}/bin:/usr/local/bin:/usr/bin:/bin
        else
                PATH=/usr/local/php/${version}/bin:$PATH $@
        fi
}

I can now easily switch between PHP versions by typing on the shell:

pe 5.3dev

or:

pe 5.4dev-zts

And each version will have a totally separated environment for me to install PEAR packages and PECL extensions in, and do my own extension development. Of course, each separated environment also comes with its own php.ini file (in /usr/local/php/{{variant}}/lib/php.ini).

This set-up makes my life a whole lot easier, and I hope it is useful for you as well. Thanks for listening!

Xdebug's Code Coverage speedup

London, UK

Friday, September 23rd 2011, 09:23 BST

Besides a debugging and development aid, Xdebug also implements the back-end code to provide code coverage information for use with PHPUnit. Code coverage tells you how much of your code base is actually being tested by your unit tests. It's a very useful feature, but sadly, it slows down PHP's execution quite a lot. One part of this slowdown is the overhead to record the information internally, but another part is because I have to overload lots of opcodes. (Opcodes are PHP's internal execution units, similar to assembler instructions) They are always overloaded even if code coverage is not used, because it's only safe to overload them for the whole request.

The upcoming Xdebug 2.2 has a few changes to improve code coverage performance. First of all, the speed with which information about code coverage is recorded has been improved by contributions by Taavi Burns. And secondly, Xdebug 2.2 features a new setting, xdebug.coverage_enable with which it is possible to disable the overloading of code coverage specific opcodes. By default that setting will still be on.

Just to show how those improvements have effect on the speed, I've run a benchmark (running Apache Zeta Components Graph's tests) to compare Xdebug 2.1.2 against Xdebug 2.2-dev.

The results are as follows:

Version	With CC	Without CC	With coverage_enable=0	Without Xdebug
2.1.2	06:44	00:49	not available	00:32
2.2-dev	05:37	00:48	00:46	00:32

Another benchmark, run by Ross McFarlane gives: @derickr Based on 3 runs each, execution of 254 tests with 1070 assertions has dropped from 19s to 12s. Nice work!.

In Xdebug 2.2 I would also like to introduce modes. Each mode will set a default configuration for Xdebug's setting to be the most optimal for that specific tasks. Examples of tasks could be: "profiling", "debugging" or "tracing". Let me know (in the comments) whether you think that's a good idea.

Remote Debugging PHP with a Firewall in the Way

London, UK

Thursday, August 25th 2011, 21:42 BST

The PHP debugging extension Xdebug has "remote" debugging capabilities for single-step debugging PHP applications. This works by setting your favourite IDE into listening mode and instructing Xdebug (with one of the handy browser extensions for example) to initiate debugging. When Xdebug is instructed it tries to make a connection to the IP address and port number that are configured in php.ini. On this IP address and port Xdebug expects to find a listening IDE. This IP address can just be 127.0.0.1 in case your IDE and web server/CLI script run on the same machine. But as Xdebug supports remote debugging, PHP/Xdebug could also be running on a totally different machine than your IDE. In that case, you need to pick the IP address of the machine on which the IDE is running as the configuration value for xdebug.remote_host. Alternatively you can set xdebug.remote_connect_back to true, so that Xdebug may simply pick up your client machine's IP address from the HTTP headers.

There could however be a firewall in the way that prevents Xdebug connecting directly to your IDE's IP address. That can be because the network you are on employs NAT in which case you could try (to convince) to get your system administrator to install a DBGp proxy. In some cases, he might not be willing to do so, or perhaps, there is simply a black box that doesn't allow either a proxy to be run on it, or port forwarding to be set-up on. In this case, there is no way Xdebug can connect to your IDE's IP address and port. Or is there?

Breaking the Firewall Down

There is another solution, at least, if you have SSH access to the development machine where Xdebug is running on. In this case, you can simply ssh in and set-up a tunnel:

ssh -R 9000:localhost:9000 username@dev.example.com

This command opens up port 9000, configured with the first 9000 in the command, for listening on the machine where you ssh-ed into. Every connection that is made to this port is then forwarded to localhost:9000, which in this case is port 9000 on the machine from where you ran the ssh command from. When you set Xdebug's xdebug.remote_host setting to localhost and xdebug.remote_port to 9000 you know have instructed Xdebug to connect to your SSH-tunneled connection which is forwarded to your local port 9000. And that is exactly where your IDE is listening for incoming debugging connections. Result: Firewall circumvented.

If you are so unfortunate to be using Windows on the client side then you don't have the luxury of being able to use the simple SSH client. However, you can set-up tunnels with putty as well. After configuring your normal session, go to the Connection, SSH, Tunnels section of the configuration and fill in Source port and Destination, and select Remote, just like in this screen shot:

Then click the Add button and you will see the following on your screen:

Don't forget to go back to the Session tab and press save. You're now ready to login and when you do so an SSH tunnel will be created just like in the Unix case above.

You can check whether it worked by running: netstat -a -n | grep 9000 on the SSH prompt after logging in. You should then see:

derick@xdebug:~$ netstat -a -n | grep 9000
tcp        0      0 0.0.0.0:9000            0.0.0.0:*               LISTEN
tcp6       0      0 :::9000                 :::*                    LISTEN

The tcp6 portion might not be there, but that's all right. There, even with Windows: Firewall circumvented.

Xdebug on github

London, UK

Wednesday, June 22nd 2011, 21:47 BST

I've just opened my Xdebug repository on github. Importing my old SVN repository was a bit of a task. With the help of Ole Marius Smestad I managed to cook up a bash script to import and fix-up the repository. In the meanwhile I've learned more about git than I ever wanted to know, but still not enough. I maintain that, although git is very powerful, it is also a lot less intuitive than SVN (or even CVS).

In any case, Xdebug is now on github, as well as the Xdebug website (http://xdebug.org), my proof-of-concept debugging client GtkDBGp and the specification of the protocol that Xdebug uses: DBGp. The issue tracker is still at the old location—http://bugs.xdebug.org—and I am not intending to change that. I will keep the SVN repository active for now.

Xdebug 2.1.1

Mon, 28 Mar 2011 08:40:00 +0000

Xdebug 2.1.1

London, UK

Monday, March 28th 2011, 09:40 BST

I've just released Xdebug 2.1.1. It is a bug fix release that primarily addresses issues in the debugging and profiling functionality of Xdebug.

Among the bug fixes is a fix that solves an issue with newer versions of the KCacheGrind profiling GUI. The newer versions are more strict with input which causes an issue with Xdebug profiler's files. Xdebug 2.1.1 solves this.

As an experiment I set up a pledge system to allow myself to work on this (and related issues) during my "work time". Twenty-four pledges were made, in about two weeks; matching the goal. Sebastian, Jan, Michael, Pale Purple, Jeff, Christoph, Karel, Yannick, Jake, Venakis, Brian, Simon, Kenneth, DM Baker, "gizmola", Ladislav, Volker, React, Michal and three anonymous supporters—thanks for your support!

Another main issue that was fixed was that line numbers (in function traces, profile files and while debugging) for "magic" function calls (such as __get(), __call() etc) were always recorded as 0. This made it impossible to set breakpoints for example.

You can find Xdebug 2.1.1's source and Windows binaries at the download page. A full ChangeLog is available as well. Through twitter you can kept up-to-date about Xdebug's development efforts and support is available through the mailinglist. If you think that Xdebug is a valuable tool, you can donate via PayPal.

Sponsoring Xdebug

Tue, 22 Mar 2011 18:30:00 +0000

Sponsoring Xdebug

London, UK

Tuesday, March 22nd 2011, 18:30 GMT

Over the past 7 years I've spend countless hours making Xdebug an awesome development and debugging tool. I love working on it; it is a good way to get familiar with PHP's "interesting" internals, and it also helps PHP developers finding (potential) issues within their code base faster.

With the 2.0 release announcement I asked users of Xdebug to send me a postcard if they liked it; and since the 2.1 announcement I mention that it is possible to give donations through PayPal. I have received quite few postcards and donations.

Recently, an issue with KCacheGrind and Xdebug's profiler functionality became known. As an experiment Sebastian suggested to see whether it would be a good idea to set-up a pledge-like system to arrange some funding so that I can dedicate my "work time" to working on Xdebug issues and features. I set-up a campaign on Pledgie for this purpose. Both Sebastian and I expected Pledgie to work a bit different than it actually did. Instead of holding on to the pledged money until the issue was implemented, it transfered the pledges directly to my PayPal account.

Twenty-four pledges were made, in about two weeks; matching the goal. Thanks Sebastian, Jan, Michael, Pale Purple, Jeff, Christoph, Karel, Yannick, Jake, Venakis, Brian, Simon, Kenneth, DM Baker, "gizmola", Ladislav, Volker, React, Michal and three anonymous supporters!

Last night I committed several patches to the Xdebug repository, including the one that sparked the idea to set-up a pledge to fund Xdebug's profiler files. These patches, and a few others, now form part of the upcoming Xdebug 2.1.1 release. I've published the source package for the first (and most likely only) release candidate: Xdebug 2.1.1RC1. Windows binaries will follow shortly. You can also install/upgrade the release candidate through PECL: pecl install xdebug-beta or pecl upgrade xdebug-beta.

The Pledgie campaign has now been closed, but I am intending to set-up new ones for more of the elaborate features—most likely starting with one related to Xdebug's code coverage functionality. In the meanwhile, please test Xdebug 2.1.1RC1, and let me know your comments about sponsoring specific Xdebug features. I plan on releasing to write up some more thoughts about that soon. I expect Xdebug 2.1.1 to come out before the end of the month. If you think Xdebug is useful, feel free to donate as well!

Debugging Variables

Thu, 10 Feb 2011 09:12:00 +0000

Debugging Variables

London, UK

Thursday, February 10th 2011, 09:12 GMT

Sometimes you want to inspect the contents of variables more closely, by looking at its internal properties. For this, PHP has the debug_zval_dump function.

The internal representation of a PHP variable container (called zval), contains the type and value of a variable, but also whether it is a reference and what its refcount is. Due to PHP's copy-on-write policy, one specific zval container can be used by multiple variables at the same time as we will see in a bit.

The refcount field contains how many symbols (variable names) point to a zval, regardless of whether a reference set is used or not. For example, both the following examples will have as end-result: two symbols and one zval:

In order for PHP to know the difference, there is an extra flag on the zval: is_ref, which is set if you assign a variable by reference with =&. It is important to know which of the situations actually occurred because PHP needs to be able to do the correct thing when a third symbol comes into play. In the first situation, a third symbol can be associated with the same zval only if it is assigned by assignment. If the third symbol is assigned by reference with something like $c =& $b; then PHP needs to duplicate (split) the zval into two zvals because only symbol b and c are linked, whereas a is distinct. Without the separation PHP will not be able to know which of the two symbols are referenced (b and c), and which one is not part of the reference set (a).

The opposite happens in the second situation. If a third symbol is assigned by reference with something like $c =& $b; then PHP can just update the refcount on the zval. If the third symbol is assigned by value with $c = $b then PHP needs to split the zval so that a and b still point to the original zval, and c to the newly created one without having links to either a or b.

This brings us to the very simple rule for when PHP needs to split upon assignment:

If the type of assigning (by-value with = or by-ref with =&) matches the value of is_ref: just update refcount by adding 1.
If the type of assigning does not match the value of is_ref: split the zval.

Now let us get back to the original issue: the inspection of the internal structure of variable contents with debug_zval_dump. When a variable is passed to a function as an argument, an assignment to the function's local scope is made; just like an assignment in a function. Which means that the same splitting rules apply. The following are (mostly) equivalent regarding on what happens to the is_ref and refcount values:

and:

PHP's debug_zval_dump takes a variable as argument for analysis and is thus also bound to the same splitting rules as outlined earlier. This means that's not really well suited for dumping a zval's internal structure as it would always modify the zval. Besides adding 1 to the refcount field, it could also force a split resulting in unexpected output:

shows:

long(42) refcount(2)

Xdebug has a similar function to display a zval's internal data: xdebug_debug_zval. This function does requires not a variable to be passed as its argument, but instead requires a variable name to be passed in. With this, the manipulation of the zval is avoided and the proper values are shown:

which shows:

a: (refcount=1, is_ref=0)=42

This is what is expected, and as bonus, it also shows the is_ref flag. PHP's bug #53895 mentions a few issues with the debug_zval_dump function. Gustavo is quite right to say that passing the variable name by-ref is not going to work, and any form of this function where the variable is passed in is not going to work. Johannes however is also right that passing just the variable name as a string might not be good enough; as you can't directly dump the zval information for for example array keys. There is an Xdebug feature request for this functionality to be implemented however. If implemented, you should be able to debug the foo array key with something like:

 3.1415);
xdebug_debug_zval('a["foo"]');
?>

Now if I only had some spare time...

Xdebug 2.1

Tue, 29 Jun 2010 14:17:00 +0000

Xdebug 2.1

London, UK

Tuesday, June 29th 2010, 15:17 BST

I've just released Xdebug 2.1. This new release contains all the bug fixes and new features that have been developed over the past three years. It provides full PHP 5.3 support, but it no longer supports PHP versions below 5.1.

A description of all the new features follows:

Error Collection

I've added xdebug_start_error_collection(), xdebug_stop_error_collection() and xdebug_get_collected_errors(), which allow you to collect all notices, warnings and error messages that Xdebug generates from PHP's error_reporting functionality so that you can output them at a later point in your script by hand.

Header Setting Interception

All functions that set HTTP headers such as with header() and setcookie() are now intercepted by Xdebug. The intercepted headers are stored internally in an array that can be retrieved by calling the xdebug_get_headers() function. This is very useful in cases where you need to test certain functionality that sets headers somewhere deep in code. This function is also used in eZ Components' test suite to test whether the correct HTTP headers are set in the MvcTools component.

Variable Assignment Tracing

The new setting xdebug.collect_assignments allows you to record changes to variables in scripts to trace files. I've already written more about it in Variable tracing with Xdebug.

"Scream" Support

The scream PECL extension disables the @ (shut-up) operator to actually see all notices, warnings and errors that PHP generates. The scream extension's functionality have been duplicated as Xdebug's xdebug.scream php.ini setting. Why disabling the @-operator is a good thing, I've already outlined in Five reasons why the shut-op operator (@) should be avoided.

Additions for Stack Traces

All HTML containers generated by Xdebug (error messages, xdebug_var_dump() output) now contain a CSS class for easier styling.

The new setting xdebug.file_link_format allows you to turn any file/line link in Xdebug's output to be decorated to a link with a specific format. For example you can set it to txmt://open/?file://%f&line=%l for opening files directly in Textmate, or gvim://%f@%l with some shell script for gvim and Firefox.

Remote Debugging

The new setting xdebug.remote_connect_back, contributed by Lucas Nealan and Brian Shire, allows Xdebug to try to make a debugging connection to the IP address from which the browser request came from. This setting is an additional solution for debugging with multiple users.

The old gdb and php3 remote debugging engines have been removed.

Overloaded var_dump

The newly introduced setting xdebug.overload_var_dump can be used to turn off Xdebug's default behavior of overriding PHP's var_dump() function with the xdebug_var_dump() function that uses pretty HTML for formatting a variable structure. It does not stop xdebug_var_dump() from working however.

Donations

You can probably imagine that writing and support Xdebug is a time-consuming effort. It's a tool that saves a lot of work during developement of applications, as well while debugging. If you think Xdebug is valuable for you, perhaps you would like to consider a donation. All donations are greatly appreciated and support future development and availablity of Xdebug.

If you want to sponsor a (new) feature in Xdebug, feel free to contact me as well.

Download and Support

The new version of Xdebug can be downloaded through the download page. A list with all changes can be found on the updates page. Support information can be found on the support page, and issues and feature requests can be filed in the bug tracker. Before asking for support, please have a look at the FAQ first.

Find my Xdebug download wizard

Mon, 03 May 2010 09:00:00 +0000

Find my Xdebug download wizard

London, UK

Monday, May 3rd 2010, 10:00 BST

Installing Xdebug seems to be a problem for some users. The main trouble is for Windows users that don't know which file to download. Over the past few days I've worked on a wizard that analyses phpinfo()'s output and for Windows users suggests:

which file to download
where to put the file
which php.ini file to modify, and how

For Unix users, it explains:

which source tarball to download
how to compile
which php.ini file to modify, and how

I hope this makes it a bit easier to get going with Xdebug. Next up (hopefully this week) is release candidate 2 for Xdebug 2.1.0.

VLD released

Mon, 12 Apr 2010 20:57:00 +0000

VLD released

London, UK

Monday, April 12th 2010, 21:57 BST

I just released a new version of VLD through PECL. This release features the path analytics code that I've outlined in an earlier article. There are also a few fixes for PHP's current trunk, as well as the possibility to format output slightly like a CSV file. That feature was used to make this documentation of opcodes.

The path analysis algorithm that VLD now has, can possibly also be used to get path/branch coverage working within Xdebug's code-coverage framework. This is however not a minor task.

Xdebug 2.1.0 RC1 released

Tue, 06 Apr 2010 13:41:00 +0000

Xdebug 2.1.0 RC1 released

Schiphol, Netherlands

Tuesday, April 6th 2010, 15:41 CEST

As earlier announced in my April Fools' announcement and on Xdebug's twitter feed, I'm now releasing Xdebug 2.1.0RC1. This is the first Release Candidate and it addresses a number of issues found in the latest beta. As I usually do in release announcements, I will also be introducing a new feature in Xdebug 2.1 in this one.

In an article that I wrote a few months ago, I illustrated a few different reasons on why the shut-op operator (@) should be avoided. Although there are a few cases where it simple can not be avoided if you want to write notice-free code, the main reason why this operator should be avoided, is because it makes debugging quite a bit more difficult if errors are hidden.

Xdebug is a debugging aid to make debugging easier. So from version 2.1.0 there is a new configuration setting — xdebug.scream — that simply disables the effects of the @ operator. That means that all errors will be shown, of course, still listening to the error_reporting and display_errors settings. This functionality is not a novel thing, and the idea was lifted from the PECL scream package. However, I think this functionality fits in very well with all the other things that Xdebug has to offer.

Just to mention it once more, I have no intention of making Xdebug closed source. I spend a considerable amount of time in adding new features and addressing issues, so I would appreciate it that if consider a donation in case Xdebug has saved you time and effort in debugging your application. If you have comments or suggestions to improve Xdebug, please write to the mailinglist.

Xdebug no longer Open Source

Thu, 01 Apr 2010 09:19:00 +0000

Xdebug no longer Open Source

London, UK

Thursday, April 1st 2010, 10:19 BST

This was obviously an April Fools' joke, Xdebug will continue to stay Open Source and free of charge.

Later today I will be releasing the first Release Candidate of Xdebug 2.1. With regret I have to announce that from this release, I will no longer provide Xdebug as an open source debugger extension. I've noticed that there are other projects making money of Xdebug's success while I only receive donations from a group of awesome supporters.

Xdebug will continue to be available for benefactors on a limited number of platforms that I have access to (Linux 32/64bit and Windows). Please refer to the FAQ for further information.

Available for PHP Extension Writing

Mon, 15 Mar 2010 12:28:00 +0000

Available for PHP Extension Writing

London, UK

Monday, March 15th 2010, 12:28 GMT

Slightly more than a month ago I left my job as team-lead of eZ Components at eZ Systems behind, to focus on something new. During the past month I've been contemplating about what to do next and realized that I do not want to take on a new full-time position right away. Instead I will be available to work on (custom) PHP extensions and internals related issues. Extensions are a great way around PHP's limitations and performance issues.

As first project I am working on a "QuickHash" extension for StumbleUpon. This extension circumvents PHP's hefty memory (and performance) overhead by providing more specific data structures. The extension currently implements integer sets and integer to integer hashes. I am now adding integer to string hashes and string to integer hashes. The QuickHash extension will be released under the PHP Licence and I will dedicate another post to it later.

If, like StumbleUpon, you are also interested in having work done on PHP or a specific extensions feel free to contact me. I'd be happy to discuss things with you.

Xdebug 2.1.0beta3 released

Sat, 27 Feb 2010 23:57:00 +0000

Xdebug 2.1.0beta3 released

London, UK

Saturday, February 27th 2010, 23:57 GMT

I've just released Xdebug 2.1.0beta3 which includes a few crash bugs as well as the issue that headers sent from PHP scripts are not actually set.

You can find the full changelog here and get the latest version from the download page.

More source analysis with VLD

Fri, 19 Feb 2010 11:27:00 +0000

More source analysis with VLD

London, UK

Friday, February 19th 2010, 11:27 GMT

VLD is a tool that I started working on years ago to visualise the opcode arrays in PHP. Opcode arrays are what PHP's compiler generates from your source code and can be compared to assembler code that is generated by a C compiler. Instead of it being directly executed by the CPU, it is instead executed by PHP's interpreter.

Over the years I've been adding some functionality, also aided by Ilia and some others, to show more information. For example Ilia has added a more verbose dumping format for opcodes (through the vld.verbosity setting) whereas I have added routines to find out which ops in oparrays can never be reached. A very simple example of the latter is shown here:

If we run the above through VLD with php -dvld.active=1 test.php, you'll see the following output (I removed the part about the script body itself):

Function test:
filename:       /tmp/test1.php
function name:  test
number of ops:  9
compiled vars:  none
line     # *  op           fetch  ext  return  operands
---------------------------------------------------------
   2     0  >   EXT_NOP
   4     1      EXT_STMT
         2      ECHO                           'Hello%21%0A'
   5     3      EXT_STMT
         4    > RETURN                         true
   7     5*     EXT_STMT
         6*     ECHO                           'This+will+not+be+executed.%0A'
   8     7*     EXT_STMT
         8*   > RETURN                         null

End of function test.

Every opcode that has a * after the number (like in 5*) is code that can not be reached, and can possibly be eliminated from the oparrays in an optimiser.

The dead code analysis routines have also made their way into Xdebug which uses them for the code coverage functionality to highlight dead code. This mostly makes sense if you are running your code coverage together with unit tests such as you can do with PHPUnit.

Recently I've been working on some new functionality to visualise all the code paths that make up each function. These new routines sit on top of the routines that do dead code analysis. Every branch instruction (such as if, but also for and foreach) is analysed and a list of branches is created. Each branch contains information about the line on which the branch starts, the starting and ending opcode numbers that belong to the branch, as well as to which other branches this branch can jump to. There can be either no linked branches (when for example a return or throw statement is found), one linked branch (for an unconditional jump) or two linked branches (on a branch instruction). However, you need to be aware that internally, PHP's opcode don't always reflect the source code exactly.

Once all the branches and their links are found, another algorithm runs to figure out which paths can be created out of all the branches. It is best to illustrate this with an example. So let us look at the following script:

In this script we have a for-loop with a nested if construct. When we run this script through VLD (with php -dvld.verbosity=0 -dvld.dump_paths=1 -dvld.active=1 test2.php) we get the following output (again, only the test() function and with some white space modifications):

Function test:
filename:       /tmp/test2.php
function name:  test
number of ops:  22
compiled vars:  !0 = $i
line     # *  op             fetch  ext  return  operands
-----------------------------------------------------------
   2     0  >   EXT_NOP
   4     1      EXT_STMT
         2      ASSIGN                             !0, 0
         3  >   IS_SMALLER                 ~1      !0, 10
         4      EXT_STMT
         5    > JMPZNZ                  9          ~1, ->18
         6  >   POST_INC                   ~2      !0
         7      FREE                               ~2
         8    > JMP                                ->3
   6     9  >   EXT_STMT
        10      IS_SMALLER                 ~3      !0, 5
   7    11    > JMPZ                               ~3, ->15
   8    12  >   EXT_STMT
        13      ECHO                               '-'
   9    14    > JMP                                ->17
  12    15  >   EXT_STMT
        16      ECHO                               '%2B'
  14    17  > > JMP                                ->6
  15    18  >   EXT_STMT
        19      ECHO                               '%0A'
  16    20      EXT_STMT
        21    > RETURN                             null

branch: #  0; line:  2- 4; sop:  0; eop:  2; out1:   3
branch: #  3; line:  4- 4; sop:  3; eop:  5; out1:  18; out2:   9
branch: #  6; line:  4- 4; sop:  6; eop:  8; out1:   3
branch: #  9; line:  6- 7; sop:  9; eop: 11; out1:  12; out2:  15
branch: # 12; line:  8- 9; sop: 12; eop: 14; out1:  17
branch: # 15; line: 12-14; sop: 15; eop: 16; out1:  17
branch: # 17; line: 14-14; sop: 17; eop: 17; out1:   6
branch: # 18; line: 15-16; sop: 18; eop: 21
path #1: 0, 3, 18,
path #2: 0, 3, 9, 12, 17, 6, 3, 18,
path #3: 0, 3, 9, 15, 17, 6, 3, 18,
End of function test.

This dump consists of a few different parts. First of all we can see some basic information containing the name, the number of ops (22) and the compiled variables. The second part is a dump of all the opcodes that make up this function. The last part contains information about all the branches and the possible paths. This information is a bit hard to visualize in its textual form, so I've also added some code that dumps this information to a file format that the GraphViz tool "dot" can use to create a pretty graph. For this we re-run the previous PHP invocation as php -dvld.dump_paths=1 -dvld.verbosity=0 -dvld.save_paths=1 -dvld.active=1 test2.php. This creates the file /tmp/paths.dot that "dot" can use. If we run dot -Tpng /tmp/paths.dot > /tmp/paths.png we end up with the following picture:

If we put this graph next to the code, we can explain how this works. Every branch is named by the number of the first opcode in that branch:

op #1 is the assignment of $i in line 4.
op #3 is the loop test in line 4. If the condition doesn't match, we jump to op #18 on line 16 that echos the newline.
op #9 is the if condition on line 6.
op #12 is when the if condition returns true and
op #15 is when the if condition returns false.
op #17 sits behind both op #12 and op #15 and makes sure there is a jump to the counting expression in #op 6.
op #6 is the post increment operation on line 4 which will then again be followed by op #3 to check whether the end of the loop has been reached.

This is of course a very simple example, but it also works for (multiple) classes and functions in a file. You just need to make sure to tell VLD that you don't want the code executed as the output could be very large. You can use the vld.execute=0 php.ini setting for that.

I hope this new functionality can spread some light on how loops etc. work in PHP. In order to play with the code, you need to check-out VLD from my SVN with svn co svn://svn.xdebug.org/svn/php/vld/trunk vld. You can also view the code on-line at http://svn.xdebug.org/cgi-bin/viewvc.cgi/vld/trunk/?root=php. Look out for a new release coming soon!