SublimePHPCoverage插件

适用于Sublime Text 2的插件，可以在编辑器中可视化PHP代码覆盖率数据。测试覆盖率数据来自Clover覆盖率文件，并在页边距中视觉显示，并在状态栏中显示摘要。

绿色（点）线至少被一个测试覆盖，红色（箭头）线未被覆盖，未注解的线不可执行，因此不计入代码覆盖率数据）。

• 适用于Sublime Text 2或3
• 在Mac OS X和Windows上进行了测试
• 当有新的覆盖率数据时，自动更新显示

安装

在开始之前，要求如下

• Sublime Text 2或3
• Package Control（可选，推荐）
• 已安装并设置了Xdebug
• 使用PHPUnit对其测试套件进行测试的PHP项目

Package Control

安装插件的简单方法是使用Package Control。转到首选项 > Package Control > 安装包，输入“PHP Coverage”，然后按Enter。已完成！查看配置部分。

手动安装

如果您打算对插件进行修改或贡献，那么手动安装插件可能最好。您需要将此Git仓库放入Sublime Text包文件夹。这取决于您的操作系统和Sublime Text版本的不同而位于不同的位置。

• Sublime Text 2
  • Windows: %APPDATA%\Sublime Text 2\Packages
  • OS X: ~/Library/Application Support/Sublime Text 2/Packages
  • Linux: ~/.Sublime Text 2/Packages（未经测试）
  • 便携式安装: Sublime Text 2/Data/Packages（未经测试）
• Sublime Text 3
  • Windows: %APPDATA%\Sublime Text 3\Packages
  • OS X: ~/Library/Application Support/Sublime Text 3/Packages
  • Linux: ~/.Sublime Text 3/Packages (未测试)
  • 便携式安装: Sublime Text 3/Data/Packages (未测试)

您可以使用Git一次性完成此操作

$ git clone git://github.com/bradfeehan/SublimePHPCoverage.git "~/Library/Application Support/Sublime Text 2/Packages/SublimePHPCoverage"

配置

SublimePHPCoverage.sublime-settings 包含多种配置选项。所有这些选项都可以在用户配置文件中单独覆盖。

此外，您可以在Sublime项目文件（例如 myProject.sublime-project）中针对每个项目设置设置。这对于设置Clover报告的路径特别有用，因为每个项目的路径可能不同。

要覆盖项目中的设置，只需将覆盖的设置放入JSON对象中。将该对象放入您的Sublime项目文件的 settings 部分，键名与 phpcoverage 相同。例如，如果您想更改特定项目的报告路径，您的Sublime项目文件可能看起来像这样

{
    "folders": [
        {
            "path": "/path/to/project"
        }
    ],
    "settings": {
        "phpcoverage": {
            "report_path": "path/to/coverage.xml"
        }
    }
}

debug (布尔值)

默认值: false

当设置为 true 时，插件将在Sublime控制台（通过 Ctrl + ` 可访问）提供详细的诊断日志。

如果您在使用插件时遇到可重现的问题，请启用此选项，并在错误报告中尽可能提供这些日志数据。

report_path (字符串)

默认值: build/logs/clover.xml

这控制插件如何为给定的PHP源文件查找覆盖率数据。当寻找某个文件的覆盖率数据时，插件会向上遍历文件的父目录，直到找到具有此名称的文件（相对于文件的父目录之一）。

例如，如果插件需要查找包含对 /path/to/my/project/foo/bar/baz.php 的覆盖率数据的文件，而 report_path 被设置为 abc/def/clover.xml，则插件将在以下位置查找覆盖率数据文件

1. /path/to/my/project/foo/bar/abc/def/clover.xml
2. /path/to/my/project/foo/abc/def/clover.xml
3. /path/to/my/project/abc/def/clover.xml
4. /path/to/my/abc/def/clover.xml
5. /path/to/abc/def/clover.xml
6. /path/abc/def/clover.xml

插件将停止在上述列表中第一个存在的文件，并将该文件假设为包含 baz.php 的覆盖率数据文件。如果列表中的所有文件都不存在，或者列表中第一个存在的文件不包含任何 baz.php 的覆盖率数据，则插件在编辑器中不会显示任何覆盖率数据。

watch_report (布尔值)

默认值: true

如果设置为 true（默认），当PHP文件在Sublime中打开时，插件将启动一个“监视器”线程，该线程监视相关覆盖率文件是否有任何更改。如果监视器检测到覆盖率文件有任何更改，它将触发更新编辑器中显示的覆盖率数据。

尽管监视器线程使用轮询来监视文件，但在大多数情况下不应引起显著的负载。但是，如果确实如此，您可以通过使用此配置选项来尝试禁用功能（并手动更新覆盖率数据）。

include (数组)

默认值: ["\.php$"]

此选项（与下文中的 exclude 一起记录）控制哪些文件名会被考虑为PHP文件，以便在编辑器中显示覆盖率数据。默认行为是仅启用以 .php 结尾的文件的插件功能。

它应该是一个字符串数组，其中每个字符串都包含一个正则表达式模式。如果数组的任何模式与文件名匹配，则文件将被包含 - 除非它还受下面所述 exclude 选项的排除。

exclude (数组)

默认值: ["[/\\]tests?[/\\].*"]

此选项（连同上面文档中的 include）控制哪些文件将被视为PHP文件，以便在编辑器中显示覆盖率数据。默认行为是禁用位于名为 test 或 tests 的文件夹中的文件的插件功能（理由是您的PHPUnit测试可能位于这些名称之一的文件夹中，它们自己的代码覆盖率数据将不存在）。

它应该是一个字符串数组，其中每个字符串都包含一个正则表达式模式。如果数组中的任何模式与文件名匹配，则该文件将被排除。这将强制禁用该文件的插件功能，不论是否已通过上面的 include 选项包含。

设置PHPUnit

PHPUnit应配置为以Clover格式输出代码覆盖率数据。覆盖率数据应存储在由report_path选项引用的位置（默认为build/logs/clover.xml）。

这可以通过PHPUnit的命令行参数来完成

~/myProject$ phpunit --coverage-clover build/logs/clover.xml

…或更理想的是，在PHPUnit的XML配置文件中

<?xml version="1.0" encoding="UTF-8"?>
<phpunit>

    <logging>
        <log type="coverage-clover" target="build/logs/clover.xml" />
    </logging>

</phpunit>

自动构建

该插件之前有一个命令可以执行PHPUnit，自动生成代码覆盖率报告。但是，从v0.2版本开始，此功能已被删除，因为现在可以使用Sublime Text的内置构建系统功能实现相同的行为。

要设置此功能，将以下类似部分添加到您的Sublime项目文件中（例如，myProject.sublime-project）

{
    "build_systems": [
        {
            "name": "PHPUnit",
            "working_dir": "$project_path",
            "cmd": [
                "vendor/bin/phpunit",
                "--coverage-clover",
                "build/logs/clover.xml"
            ]
        }
    ]
}

然后，工具>构建系统菜单中将出现新的“PHPUnit”选项。选择此选项后，您可以按⌘B运行PHPUnit测试。

用法

代码覆盖率数据文件位于正确的位置后，Sublime中打开的任何PHP文件都应该在边缘和状态栏中显示代码覆盖率数据。

免持模式

在PHPUnit测试运行结束时，如果启用watch_report设置（默认启用），插件将检测到代码覆盖率数据文件已更新，并将更新编辑器中打开的任何文件显示的代码覆盖率数据。

手动触发刷新

如果自动watch_report设置有问题，可以禁用它。在这种情况下，编辑器中显示的代码覆盖率可以手动刷新。要这样做，请转到工具>PHP覆盖率>更新当前文件，或按⌘⇧C。

故障排除

请确认代码覆盖率文件存在，并且位于正确的位置（由report_path设置引用）。

请检查代码覆盖率文件是否有针对相关文件的<file>元素。

另外，考虑启用调试模式（使用debug设置），并通过Ctrl + `访问Sublime的控制台。

请提交您可能遇到的任何其他问题作为GitHub问题。

贡献

我想了解人们对所做的更改，任何贡献都最受欢迎。以下是一些尝试使项目保持最佳状态的指导方针。

• 尽可能使代码模块化且可测试
• 尽可能为所有内容添加文档字符串，以解释其目的
• 考虑跨平台问题，以及Sublime 2与3的兼容性
• 请使用每个缩进级别4个空格
• 请确保代码行长度不超过80个字符
• 请确保README中的段落长度不超过72个字符