Garbage Collection Statistics

PHP has a built-in garbage collector, which makes it possible for PHP to free up memory that normally would be lost due to interdependent references. I wrote about the garbage collectors in previous articles.

Xdebug 2.6 provides insight into the runs of PHP's built-in Garbage Collector. There are two new functions: xdebug_get_gc_run_count(), which returns how often the Garbage Collector has run, and xdebug_get_gc_total_collected_roots(), which returns the number of variable roots that the garbage collection has collected.

There is also a new set of settings: xdebug.gc_stats_enable, xdebug.gc_stats_output_dir, and xdebug.gc_stats_output_name. When the statistics collection is enabled by setting xdebug.gc_stats_enable to true, Xdebug will write a file to the configured output directory with a name configured through xdebug.gc_stats_output_name. Just like xdebug.trace_output_name, the latter supports different format specifier to add additional information to the file names.

Instead of recording the Garbage Collection runs for the whole script, you can also selectively record this information by using xdebug_start_gcstats() and xdebug_stop_gcstats().

When PHP's garbage collector runs, Xdebug will write information about each run into a file. The format of the file is:

Garbage Collection Report
version: 1
creator: xdebug 2.6.0 (PHP 7.2.0)

Collected | Efficiency% | Duration | Memory Before | Memory After | Reduction% | Function
----------+-------------+----------+---------------+--------------+------------+---------
    10000 |    100.00 % |  0.00 ms |       5539880 |       579880 |    79.53 % | bar
    10000 |    100.00 % |  0.00 ms |       5540040 |       580040 |    79.53 % | Garbage::produce
     4001 |     40.01 % |  0.00 ms |       2563048 |       578968 |    77.41 % | gc_collect_cycles

For each run, it will write how many roots are collected, and how much % of them ends up getting freed. The duration of the Garbage Collector's run, and the memory usage before and after are also recorded, as well as how much reduction in memory usage this Garbage Collector run created. The last column shows the active function or method name when the Garbage Collection algorithm was run, or gc_collect_cycles() if it was run manually.

Profiler Enhancements

Xdebug's profiler now also collects information about memory usage. This can assist tracking down which parts of your application allocate a lot of memory, and perhaps why some memory is not freed up.

Caveat: As described above in Garbage Collection Statistics, PHP has a Garbage Collector built in, which can trigger at seemingly random times. This will distort the memory information that is recorded in the profiler's output files. In order to get better results for memory profiling, you might want to consider disabling PHP's internal garbage collector.

Additionally, Xdebug will now add a X-Xdebug-Profile-Filename HTTP header for requests for which the profiler is active. This header holds the name of the file that contains the profiling information for that request.

Remote Debugging Improvements

A new protocol feature, extended_properties, has been introduced that IDEs can opt into. When this feature is enabled, Xdebug will send variable names as Base64 encoded data to allow for characters that can not be represented safely in XML.

Another new protocol feature, notifications, has been introduced that IDEs can opt into. When this feature is enabled, Xdebug will send any Notice, Warning, or Error as an out-of-band notification over the debugging protocol to the IDE which can then display this information.

A new setting, xdebug.remote_timeout, has been added to configure how long Xdebug should wait for an IDE to acknowledge an incoming debugging connection. The default value, 200 ms, should in most cases be enough, but can be increased if you have a particularly high latency on your network and Xdebug fails to make a connection due to the low timeout.

A new function, xdebug_is_debugger_active(), can be used whether there currently is an IDE attached to Xdebug through the DBGp protocol.

Xdebug now supports debugging through Unix domain sockets. You can specify Unix domain socket "hosts" with unix:///path/to/sock, with thanks to Sara Golemon.

Xdebug now enables FD_CLOEXEC on its debugging sockets to prevent them from being leaked to forked processes, thanks to Chris Wright.

Smaller Improvements

A new setting, xdebug.filename_format, has been added to configure how Xdebug will render filenames in HTML-like stack traces. Just like xdebug.trace_output_name, it accepts a set of format specifiers that can be used to include certain aspects of a path. Xdebug 2.6 adds the specifiers below. With a full path of /var/www/vendor/mail/transport/mta.php, the able below lists what each specifier represents:

Xdebug now adds the values of superglobals to the error log as well. Previously, it would only add this information to on-screen stack traces. In order for Xdebug to show this information, you need to configure through xdebug.dump_globals and xdebug.dump.* which superglobal keys you want to see at all.

The %s format specifier is now available to be used with the xdebug.trace_output_name setting. Previously, it was only available for use with the xdebug.profiler_output_name setting.

Trace files generated with xdebug.collect_assignments now also contain assign-by-ref (=&) assignments.

Behavioural Changes

Instead of throwing a fatal error when an infinite recursion (xdebug.max_nesting_level) is detected, Xdebug now throws an Error exception instead.

Conclusion

As you can see, Xdebug 2.6 packs a whole bunch of new features and has been the cumulation of a little over a year's work. Although the majority of the work was done by myself, there were notable contributions by Arnaud Gendre, Benjamin Eberlei, Chris Wright, Emir Beganović, Frode E. Moe, Kalle Sommer Nielsen, Nikita Popov, Sara Golemon, Remi Collet, and Zaid Al Khishman.

During the year I have also launched my Patreon page, in case, you want to contribute for further development of Xdebug. Alternatively, you might want to look at my Amazon wishlist to say thank you.