shipmonk / turbocov
Coverage engine for PHP at near-native speed! 400× less driver overhead than Xdebug, 30× less than PCOV.
Package info
github.com/shipmonk-rnd/turbocov
Language:C
Type:php-ext
Ext name:ext-turbocov
pkg:composer/shipmonk/turbocov
Requires
- php: ~8.4.0 || ~8.5.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 14:10:15 UTC
README
- ⚡ Ultrafast: 400× less overhead than Xdebug, 30× less than PCOV
- 🎯 Focused: Zero overhead for code you do not measure
- 🍰 Easy-to-use: One
pie install, one line inphpunit.xml - 🛡️ Robust: A broken setup stops the run with a clear message
Comparison
| turbocov | PCOV | Xdebug | |
|---|---|---|---|
| Time added to a test run* | +3 % | +96 % | +1,237 % |
| Line coverage | ✅ | ✅ | ✅ |
| Collect only selected files | ✅ | ⚠️ slow for the rest | ⚠️ slow for the rest |
| Branch & path coverage | ❌ | ❌ | ✅ |
*Driver alone on the test suite of Carbon (6,349 tests). Run it yourself: benchmark/
Installation
pie install shipmonk/turbocov composer require --dev shipmonk/turbocov-phpunit
Usage
Tell PHPUnit to use it:
<coverage driver="ShipMonk\Turbocov\TurbocovDriver"/>
Full coverage:
php -d turbocov.collect_paths=src vendor/bin/phpunit --coverage-html coverage
PR-only coverage:
Only want coverage for what your branch changed?
git diff --name-only --diff-filter=AMR origin/master...HEAD -- '*.php' > changed.txt php -d turbocov.collect_paths=@changed.txt vendor/bin/phpunit --coverage-clover clover.xml
Execution of unlisted files has zero overhead!
This is handy for GitLab coverage vizualization
Requirements
- PHP 8.4 or 8.5
- PHPUnit 13.3 or later. For older versions, see Usage with older PHPUnit.
Settings
| Setting | Default | Description |
|---|---|---|
turbocov.enabled |
1 |
Set 0 to turn the extension off. It then has no effect at all. |
turbocov.collect_paths |
none | The files and directories that get probes. |
turbocov.exclude_paths |
none | The files and directories that get no probes. |
turbocov.exclude_pattern |
none | A PCRE pattern. Files with a matching path get no probes. |
The two path settings take one of these values:
- A list of paths with
:separator:src:config/services.php. @and the name of a list file:@changed.txt. The list file has one path on each line.
The settings apply when PHP compiles a file. Set them in php.ini or with -d, not with ini_set().
How it works
PCOV and Xdebug do work for each instruction that PHP executes. turbocov does work only when a line runs for the first time.
- PHP compiles a file into opcodes. Each opcode has a pointer to its handler.
- For a whitelisted file, turbocov replaces the handler of the first opcode of each line with a probe.
- When a probe fires, it records the line and puts the original handler back. PHP then executes the same opcode again.
- From that moment the line runs without a probe.
stop()arms the fired probes again. The cost of a test run is in proportion to the number of lines that the test touched.
turbocov does not replace the instruction loop of PHP. Code without probes runs as if the extension is not loaded.
Functions
\turbocov\ensure_can_collect(); // throw \turbocov\CannotCollectException when the collection cannot work \turbocov\start(); // start the collection; throws the same exception \turbocov\stop(); // stop the collection; file => line => 1 for the lines that ran since start() \turbocov\get_executable_lines( // file => line => -1 for each executable line of the given files ['/absolute/path/File.php'], ); \turbocov\get_debug_info( // array of debug data like skip reason, executable lines and all probes '/absolute/path/File.php', );
Usage with older PHPUnit
The problem: PHPUnit before 13.3 cannot load a custom coverage driver. It only knows PCOV and Xdebug.
The hacky solution: install turbocov in a mode where it pretends to be PCOV. PHPUnit then uses it without any change:
pie install shipmonk/turbocov --enable-turbocov-impersonate-pcov
Then run PHPUnit the same way as with PCOV:
php -d pcov.directory=src vendor/bin/phpunit --coverage-html coverage
Notes:
- You do not need
shipmonk/turbocov-phpunitor thedriverattribute inphpunit.xml. - Remove the real PCOV first. Both cannot be loaded at the same time.
pcov.directoryis required. turbocov does not guesssrclike PCOV does.- PIE warns that it cannot detect the extension after the install. That is expected, because PHP now lists it as
pcov. - This mode is a temporary aid, and a later version can remove it.
Limitations
- Not supported:
- Windows
- PHP-FPM and other web SAPIs
- Not tested yet:
- macOS on Intel
- Cannot run together with:
- Xdebug
- PCOV
- These settings (when
opcache.enable_cli=1):opcache.optimization_levelother than0opcache.jitopcache.file_cacheopcache.preloadopcache.protect_memory=1
Build from source
phpize
./configure --enable-turbocov
make
make test
Load the result with extension=/path/to/modules/turbocov.so.
Development
The scripts in dev/ need Docker.
RUN_TESTS=1 dev/build.sh 8.5 # build and run the tests dev/build.sh 8.5 pcov # build with the name pcov dev/compare-with-pcov.sh 8.5 path/File.php # compare the line data with PCOV dev/bench.sh 8.5 # compare the speed with plain PHP and PCOV
License
MIT. See LICENSE.