rtcamp/action-phpcs-code-review

PHPCS代码审查 - GitHub Action

镜像概述和主要用途

此Action是https://github.com/rtCamp/github-actions-library/的一部分，由https://github.com/rtCamp/创建。它是一个用于执行自动化https://help.github.com/en/articles/about-pull-request-reviews的GitHub Action，基于https://github.com/Automattic/vip-go-ci/，可用于任何WordPress甚至PHP项目。代码审查通过https://github.com/squizlabs/PHP_CodeSniffer执行。请注意，此Action仅执行拉取请求审查；若需审查现有项目的全部代码，需手动进行。

核心功能和特性

• 基于PHPCS进行自动化代码规范检查
• 支持自定义PHPCS编码标准
• 可排除指定文件夹和特定嗅探规则
• 通过环境变量灵活配置行为
• 支持配置文件自定义机器人审查行为
• 可跳过对草稿PR或特定PR的扫描
• 支持自定义PHP_CodeSniffer规则集文件

使用场景和适用范围

适用于需要对WordPress或PHP项目的拉取请求进行自动化代码规范检查的开发团队，尤其适合希望确保代码符合项目编码标准、减少人工审查成本的场景。

详细使用方法和配置说明

用法

1. 在GitHub仓库中创建.github/workflows/phpcs.yml（若不存在）。
2. 向phpcs.yml文件添加以下代码：

yaml
on: pull_request

name: Inspections
jobs:
  runPHPCSInspection:
    name: Run PHPCS inspection
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        ref: ${{ github.event.pull_request.head.sha }}
    - name: Run PHPCS inspection
      uses: rtCamp/action-phpcs-code-review@v2
      env:
        GH_BOT_TOKEN: ${{ secrets.GH_BOT_TOKEN }}
        SKIP_FOLDERS: "tests,.github"
        PHPCS_SNIFFS_EXCLUDE: "WordPress.Files.FileName"
      with:
        args: "WordPress,WordPress-Core,WordPress-Docs"

3. 使用https://developer.github.com/actions/creating-workflows/storing-secrets定义`GH_BOT_TOKEN`。详见GitHub令牌创建部分。

创建拉取请求或在现有拉取请求上提交时，此Action将自动运行。默认使用WordPress编码和文档标准进行审查，可通过在args: "WordPress,WordPress-Core,WordPress-Docs"行中传递不同的PHPCS编码标准修改默认设置。

4. 若需在特定拉取请求中跳过PHPCS扫描，可在PR描述中添加[do-not-scan]（可位于描述任何位置）。

5. 若需跳过对所有PHP文件的默认自动linting，可将PHP_LINT设置为false。

GitHub令牌创建

可从https://github.com/settings/tokens创建GitHub令牌。**必须**使用https://stackoverflow.com/a/29177936/4108721创建此令牌。请注意，若仓库为私有仓库，机器人账户必须有权访问该仓库。使用机器人账户的原因是：在GitHub中，不允许用户对自己的拉取请求请求更改；此外，在大型团队中，使用个人账户令牌可能会导致不必要的GitHub通知。

不同仓库类型所需的令牌权限如下：

环境变量

修改机器人行为

可在仓库根目录放置名为.vipgoci_options的配置文件来更改机器人行为。该文件必须包含有效的JSON字符串，否则将被忽略。可在此文件中添加代码以关闭支持消息或调整PHPCS严重级别。

例如，调整PHPCS严重级别：

json
{
  "phpcs-severity": 5
}

允许的选项：

• "skip-execution"
• "skip-draft-prs"
• "results-comments-sort"
• "review-comments-include-severity"
• "phpcs"
• "phpcs-severity"
• "post-generic-pr-support-comments"
• "phpcs-sniffs-include"
• "phpcs-sniffs-exclude"
• "hashes-api"
• "svg-checks"
• "autoapprove"
• "autoapprove-php-nonfunctional-changes

更多详情请查看https://github.com/automattic/vip-go-ci#configuration-via-repository-config-file。

跳过特定文件夹的PHPCS扫描

可在仓库根目录添加文件来指定不应扫描的文件夹。PHPCS对应的文件名为.vipgoci_phpcs_skip_folders，PHP Linting对应的文件名为.vipgoci_lint_skip_folders。确保这两个文件都位于仓库根目录。

这可作为SKIP_FOLDERS环境变量的替代方法。

请注意：PHPCS xml文件中排除的文件夹在此Action中不生效，原因详见https://github.com/rtCamp/action-phpcs-code-review/issues/29#issuecomment-623933663。应将所有需排除的文件夹添加到`SKIP_FOLDERS`环境变量或`.vipgoci_phpcs_skip_folders`文件中。

在这些文件中，每行列出一个需跳过的文件夹：

foo
tests/bar
vendor
node_modules

更多详情请查看https://github.com/automattic/vip-go-ci#skipping-certain-folders。

PHPCS编码标准

以下是运行时可用的PHPCS嗅探规则列表。可通过逗号分隔值同时传递多个标准。默认传递WordPress-Core,WordPress-Docs。

• MySource
• PEAR
• PHPCompatibility
• PHPCompatibilityParagonieRandomCompat
• PHPCompatibilityParagonieSodiumCompat
• PHPCompatibilityWP
• PSR1
• PSR12
• PSR2
• Squiz
• WordPress（默认）
• WordPress-Core（默认）
• WordPress-Docs（默认）
• WordPress-Extra
• WordPress-VIP
• WordPress-VIP-Go
• WordPressVIPMinimum
• Zend

自定义嗅探规则

默认支持的规则集文件名：

• .phpcs.xml
• phpcs.xml
• .phpcs.xml.dist
• phpcs.xml.dist

若仓库根目录存在phpcs.xml文件，则该文件优先，此时传递给args的值（如args: "WordPress,WordPress-Core,WordPress-Docs"）将被忽略。

若仓库没有phpcs.xml且未在工作流中指定args，则Action将回退到默认标准。

若仓库的PHPCS规则集文件不是默认文件名列表中的文件，可使用PHPCS_STANDARD_FILE_NAME环境变量指定文件名。

示例https://github.com/rtCamp/github-actions-wordpress-skeleton/blob/master/phpcs.xml可用于自定义嗅探规则。

自定义编码标准

若仓库中有自定义编码标准，可通过Composer安装并使用PHPCS_FILE_PATH环境变量指定仓库中的phpcs执行文件路径。

截图

自动化代码审查效果

限制

请注意：

1. 此Action仅对拉取请求运行，包括拉取请求创建后推送的新提交。
2. 此Action不审查添加此Action前仓库中已存在的代码。
3. 此Action不审查直接提交到分支的代码。强烈建议禁用直接提交到主分支。

许可证

MIT © 2019 rtCamp

感兴趣吗？