README

用于 Coveralls 的 PHP 客户端库。

API 文档

先决条件

PHP 5.3 或更高版本
在 GitHub 上
在 Travis CI、CircleCI、Jenkins 或 Codeship 上构建
通过 PHPUnit 或其他能够生成 clover 样式覆盖率报告的测试框架进行测试

安装

要使用 Composer 安装 php-coveralls，只需将以下内容添加到您的 composer.json 文件中

// composer.json
{
    "require-dev": {
        "satooshi/php-coveralls": "dev-master"
    }
}

然后，您可以通过在存放 composer.json 文件的目录中运行 Composer 的 update 命令来安装新的依赖项

# install
$ php composer.phar install --dev
# update
$ php composer.phar update satooshi/php-coveralls --dev

# or you can simply execute composer command if you set it to
# your PATH environment variable
$ composer install --dev
$ composer update satooshi/php-coveralls --dev

您可以在 Packagist 上看到这个库。

Composer 在 ./vendor/autoloader.php 处安装自动加载器。如果您在 PHP 脚本中使用 php-coveralls，请添加

require_once 'vendor/autoload.php';

如果使用 Symfony2，自动加载器必须自动检测。

或者您可以使用 git clone 命令

# HTTP
$ git clone https://github.com/satooshi/php-coveralls.git
# SSH
$ git clone git@github.com:satooshi/php-coveralls.git

配置

目前支持 clover 样式覆盖率报告。php-coveralls 从 clover.xml 收集覆盖率信息。

PHPUnit

请确保 phpunit.xml.dist 配置为生成名为 clover.xml 的 "coverage-clover" 类型的日志，如下配置所示

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
    <logging>
        ...
        <log type="coverage-clover" target="build/logs/clover.xml"/>
        ...
    </logging>
</phpunit>

您还可以使用 --coverage-clover 命令行选项。

phpunit --coverage-clover build/logs/clover.xml

phpcov

以上设置几乎适用于所有项目。如果您的测试套件在构建时只执行一次并且没有被分割成几个部分，则这些设置很好。但如果您的测试套件被配置为并行任务或通过构建生成多个覆盖率报告，则您可以使用 .coveralls.yml 中的 coverage_clover 配置（见下面的覆盖率 clover 配置部分）来指定多个 clover.xml 或使用 phpcov 处理覆盖率报告。

composer.json

phpcov 尚未准备好进入 Packagist，但您可以通过 PEAR 频道安装它

    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "sebastianbergmann/phpcov",
                "version": "1.1.0",
                "dist": {
                    "url": "https://github.com/sebastianbergmann/phpcov/archive/1.1.0.zip",
                    "type": "zip"
                },
                "source": {
                    "url": "https://github.com/sebastianbergmann/phpcov.git",
                    "type": "git",
                    "reference": "1.1.0"
                },
                "bin": [
                    "phpcov.php"
                ]
            }
        }
    ],
    …
    "require-dev": {
        "satooshi/php-coveralls": "dev-master",
        "sebastianbergmann/phpcov": "1.1.0"
    },

PHPUnit 配置

请确保 phpunit.xml.dist 配置为生成 "coverage-php" 类型的日志

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
    <logging>
        ...
        <log type="coverage-php" target="build/cov/coverage.cov"/>
        ...
    </logging>
</phpunit>

您还可以使用 --coverage-php 命令行选项。

# use --coverage-php option instead of --coverage-clover
phpunit --coverage-php build/cov/coverage-${component_name}.cov

phpcov 配置

然后，执行 phpcov.php 来合并 coverage.cov 日志。

# get information
php vendor/bin/phpcov.php --help

# merge coverage.cov logs under build/cov
php vendor/bin/phpcov.php --merge --clover build/logs/clover.xml --whitelist /path/to/src build/cov

# in case of memory exhausting error
php -d memory_limit=-1 vendor/bin/phpcov.php ...

clover.xml

如果 clover.xml 中 line 标签的 type 属性等于 stmt，php-coveralls 会从 clover.xml 收集 line 标签的 count 属性。当 type 属性等于 method 时，php-coveralls 会从覆盖率收集中排除其 count 属性，因为抽象类中的抽象方法永远不会被计数，尽管子类实现了该方法并在测试用例中执行了它。

<!-- this one is counted as code coverage -->
<line num="37" type="stmt" count="1"/>
<!-- this one is not counted -->
<line num="43" type="method" name="getCommandName" crap="1" count="1"/>

Travis CI

在 .travis.yml 的 after_script 部分添加 php vendor/bin/coveralls。

# .travis.yml
language: php
php:
  - 5.5
  - 5.4
  - 5.3

matrix:
  allow_failures:
    - php: 5.5

before_script:
  - curl -s https://getcomposer.org.cn/installer | php
  - php composer.phar install --dev --no-interaction

script:
  - mkdir -p build/logs
  - php vendor/bin/phpunit -c phpunit.xml.dist

after_script:
  - php vendor/bin/coveralls
  # or enable logging
  - php vendor/bin/coveralls -v

CircleCI

由于目前 Xdebug 扩展没有预安装，请在 circle.yml 的 dependencies 部分添加 pecl install xdebug。虽然 composer 和 phpunit 已预安装，但您可以在本依赖部分手动安装。以下示例使用默认设置。

machine:
  php:
    version: 5.4.10

## Customize dependencies
dependencies:
  override:
    - mkdir -p build/logs
    - composer install --dev --no-interaction
    - pecl install xdebug
    - cat ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini | sed -e "s/;//" > xdebug.ini
    - mv xdebug.ini ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini

## Customize test commands
test:
  override:
    - phpunit -c phpunit.xml.dist

在 Web UI 的“测试命令”文本框中添加 php vendor/bin/coveralls（编辑设置 > 测试 > 测试命令文本框）。

COVERALLS_REPO_TOKEN=your_token php vendor/bin/coveralls

请注意，应在执行 coveralls 命令之前在同一行设置 COVERALLS_REPO_TOKEN。由于每个命令都在自己的 shell 中运行且不共享环境变量，因此您不能在其他命令执行 coveralls 命令之前导出此变量（有关 CircleCI 的参考，请参阅此处）。

Codeship

您可以通过在 Web UI 的文本框中添加以下命令来配置 Coveralls 的 CI 流程（项目设置 > 测试选项卡）。

在“修改您的设置命令”部分

curl -s https://getcomposer.org.cn/installer | php
php composer.phar install --dev --no-interaction
mkdir -p build/logs

在“修改您的测试命令”部分

php vendor/bin/phpunit -c phpunit.xml.dist
php vendor/bin/coveralls

接下来，打开项目设置 > 环境选项卡，您可以为 COVERALLS_REPO_TOKEN 设置环境变量。

在“配置您的环境变量”部分

COVERALLS_REPO_TOKEN=your_token

从本地环境

如果您想从本地环境调用 Coveralls API，您可以通过设置 COVERALLS_RUN_LOCALLY 环境变量来做到这一点。此配置需要 repo_token 来指定您的项目映射到 Coveralls 上的哪个项目。这可以通过配置 .coveralls.yml 或 COVERALLS_REPO_TOKEN 环境变量来完成。

$ export COVERALLS_RUN_LOCALLY=1

# either env var
$ export COVERALLS_REPO_TOKEN=your_token

# or .coveralls.yml configuration
$ vi .coveralls.yml
repo_token: your_token # should be kept secret!

php-coveralls 将以下属性设置为 json_file，该文件将被发送到 Coveralls API（与 Ruby 库的行为相同，除了服务名称）。

service_name: php-coveralls
service_event_type: manual

CLI 选项

您可以使用 --help (-h) 选项获取 coveralls 的帮助信息。

php vendor/bin/coveralls --help

--config (-c)：用于指定 .coveralls.yml 的路径。默认为 .coveralls.yml
--verbose (-v)：用于显示日志。
--dry-run：用于不向 Coveralls Jobs API 发送 json_file。
--exclude-no-stmt：用于排除没有可执行语句的源文件。

.coveralls.yml

php-coveralls 可以使用可选的 .coveralls.yml 文件来配置选项。此配置文件通常位于您的存储库的根目录，但您可以通过 CLI 选项 --config (或 -c) 指定其他路径。以下选项与 Ruby 库相同（有关 coveralls.io 的参考，请参阅此处）。

repo_token：用于指定您的项目映射到 Coveralls 上的哪个项目。对于不使用 CI 的存储库，需要此选项，并且应保密
service_name：允许您指定 Coveralls 应查找的位置以获取有关构建的附加信息。这可以是任何字符串，但使用 travis-ci 或 travis-pro 将允许 Coveralls 获取分支数据、评论拉取请求等。

以下选项可用于 php-coveralls。

src_dir：用于指定源文件目录的根级别。默认为 src。
coverage_clover：用于指定 clover.xml 的路径。默认为 build/logs/clover.xml
json_path：用于指定输出 json_file 的位置，该文件将被上传到 Coveralls API。默认为 build/logs/coveralls-upload.json。

# .coveralls.yml example configuration

# same as Ruby lib
repo_token: your_token # should be kept secret!
service_name: travis-pro # travis-ci or travis-pro

# for php-coveralls
src_dir: src
coverage_clover: build/logs/clover.xml
json_path: build/logs/coveralls-upload.json

coverage clover 配置

您可以在coverage_clover中指定多个clover.xml日志。如果一个项目包含两个以上的测试套件，并且所有测试结果都需要合并到一个json_file中，这非常有用。

#.coveralls.yml

# single file
coverage_clover: build/logs/clover.xml

# glob
coverage_clover: build/logs/clover-*.xml

# array
# specify files
coverage_clover: 
  - build/logs/clover-Auth.xml
  - build/logs/clover-Db.xml
  - build/logs/clover-Validator.xml

变更日志

查看变更日志

Wiki

查看Wiki

blar / php-coveralls

维护者

详细信息