README

PHPUnit Coverage Listener是一个实用库，允许您处理PHPUnit代码覆盖率信息，并通过cURL将其发送到远程位置。

PHPUnit Coverage Listener包的主要目标是提供一个机制，生成名为coverage.json的有效负载数据（从PHPUnit代码覆盖率信息），并将其发送到远程位置，结构如下（简化版）

{
    "repo_token": "s3cr3th4sh",
        "run_at": "2013-01-20 00:10:10 -0000",
        "source_files": [
        {
            "name": "Resource.php",
            "source": "<?php \n  echo 'Hello World'\n", // Source code contains 2 lines
            "coverage": [null, 2]                       // Coverage information on each lines
        },
        //... other source information
    ],
    "git": {
        "branch":"master",
        "head" : {
            "id":"50b111bc45ba9af702ea3230c8e44bd5e4060668",
            "author_name": "toopay",
            "author_email": "[email protected]",
            "message": "Commit message"
        },
        "remotes" : [{
            "name": "origin",
            "url": "[email protected]:php-loep/phpunit-coverage-listener.git",
            "fetch": "+refs/heads/*:refs/remotes/origin/*"
        }]
    }
}

然后在目标服务器上，您可以按以下方式接受有效负载（简化版）

<?php

$success = false;

if (!empty($_FILES) && isset($_FILES['json_file'])) {
    $target = __DIR__.'/coverage.json';
    move_uploaded_file($_FILES['json_file']['tmp_name'], $target);
    $success = 'Saved into http://'.$_SERVER['HTTP_HOST'].'/coverage.json';
}

header('Content-Type: application/json');
die(json_encode(compact('success')));

上述JSON数据可以进一步处理，以以符合您特定需求的方式公开有关您的代码覆盖率信息的有用信息。《Coveralls》服务将是一个完美的例子。

要求

• PHP >= 5.3.3

安装

通过Composer

composer require league/phpunit-coverage-listener

基本用法

假设您想在每次Travis作业成功构建时发送一个有效负载数据给Coveralls。您需要做的就是将以下部分添加到您的phpunit配置文件中，该配置文件由.travis.yml使用（在开发环境中通常不需要这样做）

<logging>
    <log type="coverage-clover" target="/tmp/coverage.xml"/>
</logging>
<listeners>
    <listener class="League\PHPUnitCoverageListener\Listener">
        <arguments>
            <array>
                <element key="printer">
                  <object class="League\PHPUnitCoverageListener\Printer\StdOut"/>
                </element>
                <element key="hook">
                  <object class="League\PHPUnitCoverageListener\Hook\Travis"/>
                </element>
                <element key="namespace">
                    <string>Your\Package\Namespace</string>
                </element>
                <element key="repo_token">
                    <string>YourCoverallsRepoToken</string>
                </element>
                <element key="target_url">
                    <string>https://coveralls.io/api/v1/jobs</string>
                </element>
                <element key="coverage_dir">
                    <string>/tmp</string>
                </element>
            </array>
        </arguments>
    </listener>
</listeners>

就是这样。

高级用法

如您在前一节中注意到的那样，为了正常工作，Listener类需要知道一些事情。它们通过listener arguments指令从您的phpunit配置中传递。

下表分别描述了每个配置选项

printer

此选项包含PrinterInterface，Listener类将在多个位置使用它。在前面的部分中，我们将其设置为使用StdOut打印机，该打印机将任何输出信息直接打印到标准输出。只要您的打印机类实现了所需的接口，您就可以使用自己的打印机类。

hook

此选项允许您钩入Listener的生命周期。HookInterface有两个方法要实现：beforeCollect和afterCollect。它将接收Collection数据，然后在每个钩点处修改或对数据进行某些操作。在前面的示例中，Travis钩实际上只包含以下代码

public function beforeCollect(Collection $data)
{
    // Check for Travis-CI environment
    // if it appears, then assign it respectively
    if (getenv('TRAVIS_JOB_ID') || isset($_ENV['TRAVIS_JOB_ID'])) {
        // Remove repo token
        $data->remove('repo_token');

        // And use travis config
        $travis_job_id = isset($_ENV['TRAVIS_JOB_ID']) ? $_ENV['TRAVIS_JOB_ID'] : getenv('TRAVIS_JOB_ID');
        $data->set('service_name', 'travis-ci');
        $data->set('service_job_id', $travis_job_id);
    }

    return $data;
}

目前存在 Travis 和 Circle 钩子。您可以注册一个适合您需求的自定义钩子类，只要它实现了所需的接口。

命名空间

可以将选项 namespace 字符串传递给监听器，这样生成的覆盖率信息将使用“相对”名称而不是字面文件路径。例如，如果您的源是 src/My/Package/Resource.php，并且您将 My\Package 作为命名空间选项传递，则覆盖率有效负载数据中的生成文件名将是 My/Package/Resource.php。

repo_token

此选项可以是任何内容。时间戳？Coveralls账户令牌？Jenkins构建令牌？由您决定。但仍然需要在监听器类中提供此选项。

目标URL

此选项可以是任何有效的URL。例如，如果您使用Coveralls，则可以将此选项设置为它的REST端点：https://coveralls.io/api/v1/jobs。

覆盖率目录

您在此处指定的目录 必须 与PHPUnit生成coverage.xml报告的目录相同。监听器还将在该目录中输出coverage.json，因此请确保此目录可写。

发送

默认情况下，此库的目的是收集和生成代码覆盖率数据，然后将这些有效负载数据发送到远程位置。但如果您只想收集和生成数据，请在监听器参数数组指令中添加以下选项

<element key="send">
    <integer>0</integer>
</element>

。

更改日志

请参阅更改日志文件

贡献

请参阅CONTRIBUTING以获取详细信息。

支持

错误和功能请求在GitHub上进行跟踪

许可证

PHPUnit Coverage Listener是在MIT许可证下发布的。有关详细信息，请参阅捆绑的LICENSE文件。