Implementing Incremental PHP Code Coverage with php-code-coverage and pcov

In many development teams, insufficient self‑testing leads to frequent production bugs, so the authors propose using data‑driven code‑coverage monitoring to objectively assess test completeness.

Code coverage is introduced as a white‑box testing metric, describing three standard levels: line (statement) coverage, branch (condition) coverage, and path (assertion) coverage, with the hierarchy path > branch > line.

The primary tool examined is php-code-coverage , an open‑source library that leverages Xdebug to collect execution data and generate HTML, XML, or text reports, but it originally supports only full‑project coverage.

To avoid instrumenting every source file, four configuration approaches are evaluated (php.ini prepend, per‑module include, nginx prepend, and entry‑file include); the fourth method—adding a prepend file to the main entry script—was adopted for its simplicity and coverage completeness.

Because full‑project reports contain unnecessary data, the team adds incremental coverage support by generating a diff between the test branch and master, using the diff as a whitelist for coverage collection, filtering irrelevant interfaces, and creating a dedicated report command.

Performance problems caused by Xdebug (e.g., interface latency up to 10 s) lead to switching to the pcov extension, which focuses solely on coverage and offers superior speed; upgrading to a newer php‑code‑coverage version compatible with pcov required addressing PHP version constraints.

Additional issues such as report‑generation timeouts (due to many individual coverage files) and GitLab diff size limits are solved by consolidating coverage data into a single file and using raw git diff commands for diff extraction.

After these enhancements, the coverage tool is integrated into the project workflow, requiring an 80 % coverage threshold before code promotion, and has proven effective in improving test reliability across multiple projects.