php-coveralls

Send coverage information to Coveralls

$ php-coveralls

$ php-coveralls [[-r|--root_dir]] [path/to/directory]

$ php-coveralls [[-c|--config]] [path/to/.coveralls.yml]

$ php-coveralls [[-v|--verbose]]

$ php-coveralls --exclude-no-stmt

$ php-coveralls [[-e|--env]] [test|dev|prod]

$ php-coveralls [[-x|--coverage_clover]] [path/to/first_clover.xml] --coverage_clover [path/to/second_clover.xml]

$ php-coveralls [[-o|--json_path]] [path/to/coveralls-upload.json]

php-coveralls [OPTIONS] <INPUT_FILE>
php-coveralls --clover <CLOVER_XML_FILE>
php-coveralls --json <JSON_FILE>
php-coveralls --coverage-bin <COVERAGE_BIN_FILE>

--clover
    Specifies the path to the Clover XML coverage report file generated by PHPUnit.

--json
    Specifies the path to a JSON coverage report file.

--coverage-bin
    Specifies the path to a serialized php-code-coverage data file.

--config-file
    Specifies an alternative path to the .coveralls.yml configuration file.

--root-dir

php-coveralls is a command-line utility designed to integrate PHP code coverage data with the Coveralls.io service. Coveralls.io is a web-based platform that tracks and visualizes code coverage over time, helping developers maintain and improve code quality.

This tool acts as a bridge, taking coverage reports generated by PHPUnit (typically in Clover XML format) or other PHP coverage tools, processing them, and then submitting them to Coveralls.io. It's most commonly employed in Continuous Integration (CI) environments, such as Travis CI, CircleCI, or GitHub Actions. After running automated tests and generating a coverage report, php-coveralls is executed to upload this data.

This allows teams to immediately see the impact of new code on overall test coverage, identify untested areas, and enforce coverage thresholds. The tool handles the conversion of various coverage formats into the Coveralls.io-compatible JSON format, and it automatically detects CI environment variables to associate reports with specific builds, branches, and pull requests. By providing historical coverage trends and per-file/per-line coverage details, php-coveralls significantly enhances visibility into the test suite's effectiveness, promoting better development practices and ensuring robust applications.

php-coveralls relies on external tools (like PHPUnit) to generate the initial coverage reports. Ensure these tools are correctly configured and producing valid output in a supported format (Clover XML, JSON, or php-code-coverage binary).

Network connectivity is required to send data to Coveralls.io. Environment variables for CI services (e.g., CI_NAME, CI_BUILD_NUMBER) are crucial for proper report attribution on Coveralls.io.

1. Install php-coveralls: Use Composer: composer require --dev satooshi/php-coveralls.
2. Configure PHPUnit for coverage: Ensure phpunit.xml is set up to generate a Clover XML report (e.g., ).
3. Run tests and generate coverage: Execute PHPUnit: vendor/bin/phpunit --coverage-clover build/logs/clover.xml.
4. Submit to Coveralls.io: Run php-coveralls: vendor/bin/php-coveralls --clover=build/logs/clover.xml -v.
5. CI Integration: Configure your CI service (e.g., Travis CI, GitHub Actions) to run steps 3 and 4 after a successful build. Ensure the COVERALLS_REPO_TOKEN environment variable is set in your CI environment for private repositories.

php-coveralls was created to address the need for a PHP-specific client to integrate with the Coveralls.io service, similar to existing clients for Ruby, Python, and JavaScript. Its development has focused on supporting various PHP code coverage formats and seamlessly integrating with popular CI/CD platforms, making it a staple for PHP projects aiming for continuous code quality monitoring.

phpunit(1), composer(1), git(1)