1: <?php
2: $c = array(
3:      'name' => 'derickr',
4:      'age' => 'yeah right',
5: );
6: ?>

line     #* op                 return  operands
-------------------------------------------------
   3     0  EXT_STMT
                 1  INIT_ARRAY         ~0      'derickr', 'name'
   4     2  ADD_ARRAY_ELEMENT  ~0      'yeah+right', 'age'
   5     3  ASSIGN                     !0, ~0
   7     4  EXT_STMT
                 5  RETURN                     1

Which lines have code on them?

Just enabling code coverage with the xdebug_start_code_coverage() function will give you every single line that has been hit while running your script. But it does not say anything about which lines you have not hit. Xdebug can also calculate this. In order to do so, the option XDEBUG_CC_UNUSED needs to be passed to xdebug_start_code_coverage(). Turning this specific option on makes Xdebug scan every execution unit (opcode) in your application. This adds a lot of overhead. Of course, Xdebug does try to analyse each function (or method) only once. A bug in this detection actually made it not scan as often as it should, but that will soon be fixed through PR #134.

Which lines can be executed?

Besides code coverage and finding out which lines can be covered, Xdebug can also find which parts of your code can never be reached: dead code.

I implemented the algorithms to find dead code in another one of my side projects first: VLD. It is a tool that shows PHP's internal compilation units (opcodes), just like in the array example above. Because it is a much smaller and simpler tool, testing new algorithms out in it makes things a lot easier than trying to get it into Xdebug immediately.

Anyway, the dead code analysis can be activated by passing in the XDEBUG_CC_DEAD_CODE option. It does not make a lot of sense to do this without XDEBUG_CC_UNUSED and you can combine them with the | operator as they are parts of a bitfield:

xdebug_start_code_coverage( XDEBUG_CC_DEAD_CODE | XDEBUG_CC_UNUSED );

With dead code analysis enabled, Xdebug will scan each function and method's oparray as usual, but it will also follow all branch points (such as the ones created by if, while, for, etc.), to see which branches can not be reached theoretically. This finds for example return; before some other code, or a throw with code following. After following all the branch and exit points, Xdebug then finds which opcodes are not part of any branch. It eliminates them from the lines that can be executed, as found by the checks run for XDEBUG_CC_UNUSED.

In the resulting array structure that xdebug_get_code_coverage() returns, there are now three possible values for each line: 1, to signal that code has been executed, -1 if there was no code executed on that line, and -2 if there was no executable code at all on that specific line.

An example script (article-test.php):

<?php
function test()
{
        if ( $a == 42 )
        {
                echo "The argument is 42\n";
        }
        else
        {
                throw new Exception( "Not 42!" );
                echo "nope\n";
        }
}

try
{
        test( 42 );
}
catch ( Exception $e )
{
        echo "Do nothing!\n";
}
?>

Executed through a runner (article-simple.php):

<?php
xdebug_start_code_coverage( XDEBUG_CC_DEAD_CODE | XDEBUG_CC_UNUSED );

include 'article-test.php';

var_dump( xdebug_get_code_coverage() );
?>

Produces (after some formatting):

Do nothing!
array(2) {
  '/home/httpd/html/test/xdebug/code-coverage/article-test.php' =>
  array(12) {
        [2] => int(1)
        [4] => int(1)
        [5] => int(1)
        [6] => int(-1)
        [7] => int(-1)
        [10] => int(1)
        [11] => int(-2)
        [13] => int(-1)
        [17] => int(1)
        [19] => int(1)
        [21] => int(1)
        [24] => int(1)
  }
  '/home/httpd/html/test/xdebug/code-coverage/article-simple.php' =>
  array(2) {
        [4] => int(1)
        [6] => int(1)
  }
}

If we were to use PHP CodeCoverage instead, the runner script (article.php) looks like:

<?php
require 'vendor/autoload.php';

$coverage = new PHP_CodeCoverage;

$coverage->start( 'article' );

include 'article-test.php';

$coverage->stop();

$writer = new PHP_CodeCoverage_Report_HTML;
$writer->process($coverage, '/tmp/code-coverage-article');
?>

Which outputs:

Lines 6 and 7 have not been executed, because we didn't pass in the variable $a. Line 13 has not been executed because the code never reached the end of the function as we jumped out with the throw in line 10. The output also shows that the code on lines 11 and 12 can not be reached (because of the throw preceding it).

This concludes the current code coverage features in Xdebug, in the second part I will cover an upcoming feature.