php-coveralls
Submit PHP code coverage reports to Coveralls
TLDR
Send coverage information to Coveralls
Send coverage information to Coveralls for a specific directory
Send coverage information to Coveralls with a specific config
Send coverage information to Coveralls with verbose output
Send coverage information to Coveralls excluding source files with no executable statements
Send coverage information to Coveralls with a specific environment name
Specify multiple Coverage Clover XML files to upload
Output the JSON that will be sent to Coveralls to a specific file
SYNOPSIS
php-coveralls [options]
PARAMETERS
--version
Display the current version of php-coveralls.
--help
Display help information about the command and its options.
--coverage_clover
Specify the path to the Clover XML coverage file generated by PHPUnit or similar tool.
--json_path
Specify the path to a JSON file containing additional information for the Coveralls job, often generated by CI/CD systems.
--exclude
Exclude a directory from the coverage analysis.
--dry-run
Perform a dry run; validate the input and configuration without actually sending data to Coveralls.
--verbose
Enable verbose output for debugging.
DESCRIPTION
The `php-coveralls` command is a tool used to send PHP code coverage reports generated by tools like PHPUnit to the Coveralls.io service. Coveralls provides insights into code test coverage, helping developers identify untested areas and improve code quality. This tool automates the process of submitting coverage data, which would otherwise require manual configuration and handling of coverage files. It streamlines the continuous integration workflow, allowing for easy tracking of coverage trends and ensuring that every commit is properly tested.
It typically integrates with CI/CD pipelines (e.g., Travis CI, CircleCI, GitHub Actions) to automatically submit coverage data after running tests. The tool collects coverage data from PHPUnit or similar tools, formats it according to Coveralls' specifications, and then transmits it to the Coveralls.io API. This enables developers to quickly visualize code coverage metrics, identify coverage gaps, and ultimately improve the reliability and maintainability of their PHP projects.
CAVEATS
Requires a Coveralls.io account and proper configuration within the CI/CD environment. Ensure the coverage file path is accurate and that the necessary environment variables (e.g., repo token) are set.
INTEGRATION WITH CI/CD
The primary use case for `php-coveralls` is within Continuous Integration/Continuous Delivery (CI/CD) pipelines. After tests are executed, the coverage data is generated and then submitted to Coveralls using this command. Common CI/CD platforms include Travis CI, CircleCI, GitHub Actions, GitLab CI, and Jenkins.
ENVIRONMENT VARIABLES
The `php-coveralls` tool often relies on environment variables to configure the Coveralls job, such as the repository token (`COVERALLS_REPO_TOKEN`) and CI build information.
These variables are typically provided by the CI/CD environment.
CONFIGURATION FILES
While command-line options are the primary way to configure `php-coveralls`, some settings can also be specified through configuration files in the project, although this is less common. The `json_path` argument points to a json config file
HISTORY
The `php-coveralls` command and associated library were created to simplify the process of submitting PHP code coverage data to Coveralls.io. Prior to this, developers often had to manually format and upload coverage data, which was time-consuming and error-prone. The tool has evolved to support various CI/CD environments and coverage formats, becoming an integral part of many PHP development workflows focused on code quality and test coverage.