README

此工具旨在运行一些检查，主要基于当前提交（或未提交的更改）与目标分支（或父祖先）之间的更改。

根据其使用位置，它尽力将差异限制在仅更改的行或文件中。

此工具还具有一些其他功能，在本文档中解释。

在撰写本文时，所有功能都硬编码在 otgs-checks-php 中。
存在一定程度的配置，可以允许控制行为。

以下是按执行顺序排列的每个功能。

只要任何功能失败，该工具就会以非零代码存在。

功能

WordPress 插件：验证版本（仅限非 CI 环境）

此功能与更改的文件无关，但会在其他任何功能之前运行。

由于 GitLab-CI 在运行作业时不会克隆整个存储库，因此如果设置了 CI 环境变量，则忽略此功能。但是，如果设置了 CI_COMMIT_TAG 环境变量，则不会忽略此功能。

1. 它首先搜索当前存储库的最新标签（使用 git describe --abbrev=0）
2. 它尝试找到主要插件文件
3. 它尝试找到在主要插件文件中定义版本号的位置
4. 它将这些值与第 1 点中找到的值进行比较：如果第 1 点更大，则检查失败

从主要插件文件中提取版本号的操作规则硬编码在 \OTGS\DiffChecks\WP\Plugins::__construct 中。
但是，它们可以通过两种方式扩展。

环境变量

如果脚本找到名为 OTGS_CI_REPLACEMENTS 或 OTGS_CHECKS_VERSION_PATTERNS 的环境变量，则将使用它们。

OTGS_CI_REPLACEMENTS 替换 OTGS_CHECKS_VERSION_PATTERNS。

OTGS_CHECKS_VERSION_PATTERNS 是 CI 中通常使用的变量。

该变量必须包含一个 JSON 对象。JSON 对象必须是对象的数组。数组的每个元素必须具有

• searchPattern 键：匹配版本号的分组正则表达式。
• 可选的 matchingGroup 键：如果提供，则工具将使用此值来识别版本号（基于零）。

如果没有提供或设置 matchingGroup 或设置为 "last"，则工具将从 preg_match 中查找最后一个匹配项。

OTGS_CI_REPLACEMENTS 的一个示例，用于 WPML 项目

[
  {
    "searchPattern": "(Version:\\s*)(\\d*.*)",
    "replacePattern": "%1{{tag}}",
    "matchingGroup": 2
  },
  {
    "searchPattern": "(GRAVITYFORMS_MULTILINGUAL_VERSION\\',\\s*\\')(\\d*.*)(\\')",
    "replacePattern": "%1{{tag}}%3",
    "extractSemVer": true,
    "matchingGroup": 2
  },
  {
    "searchPattern": "(wpml.org\\/version\\/wpml-)([\\d\\-*]*)(\\/\">WPML )([\\d\\.*]*)( release notes)",
    "replacePattern": "%1{{tag-slug}}%3{{tag}}%5",
    "matchingGroup": 2
  },

调用 \OTGS\DiffChecks\WP\Plugins::checkVersion

如果在此库中使用了自定义脚本（即，不是通过调用 otgs-checks-php），则可以使用 \OTGS\DiffChecks\WP\Plugins::checkVersion 来自定义模式。

在这种情况下，将忽略硬编码模式和环境变量。

\OTGS\DiffChecks\WP\Plugins::checkVersion 接受两个参数

• 要使用的 "有效版本"
• (可选) 模式数组：与 JSON 形式相同的规范，但作为关联数组

静态代码分析

1. 在内存中生成了一个修改的 PHP 文件列表
2. 在临时目录中生成了一个差异文件
3. 对所有修改的文件进行检查，以查找重复的代码（《phpcbf》）
4. 对每个修改的文件进行检查，以进行基本检查（《php -l -d》）
5. 编码标准与修改的行进行核对（phpcs --standard=./phpcs.xml）
6. 代码兼容性检查针对修改的行（phpcs --standard=./phpcs.compatibility,xml）

安装

运行 composer require --dev otgs/diff-checks。

使用方法

最直接的使用方式是在您的代码做出一些更改后调用 ./vendor/bin/otgs-check-php。

建议将此调用添加到您的 Git 预提交钩子中。

此外，您可能希望在 CI 中的其他测试之前运行此调用。

然而，在撰写本文时，构建良好的差异的唯一方法是提供一个目标分支。

在 GitLab 中，这只能在 CI 作业的 only 数组中至少有 merge_requests 时实现。

当此类作业运行时，提供以下两个环境变量

• CI_MERGE_REQUEST_TARGET_BRANCH_NAME
• CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

（欢迎贡献改进构建差异文件的方法）

以下是从 WPML 中摘录的 gitlab-ci.yml 示例

Prepare <Cache>:
    stage: pre-flight
    cache: &cache-commit
        untracked: true
        key: "${CI_COMMIT_SHA}"
        paths:
            - node_modules/
            - vendor/
        policy: push
    when: always
    image: registry.otgs.work/infrastructure/docker-images/phpunit:7.3
    script:
        - composer install
        - npm install

Diff <PHP>:
    stage: quality
    cache:
        <<: *cache-commit
        policy: pull
    when: on_success
    image: registry.otgs.work/infrastructure/docker-images/phpunit:7.3
    tags:
        - autoscale
    script:
        - composer install
        - ./vendor/bin/otgs-check-php
    only:
        - merge_requests

缓存

尽管不是必需的，但缓存键对于加快管道速度非常有用。

在 Prepare <Cache> 中，使用 push 策略生成缓存（即，CI 不会尝试读取它，但它会将其保存到缓存中）。

在 Diff <PHP>（以及所有其他作业）中，使用 pull 策略定义缓存（CI 将尝试获取它，如果缓存不可用，则优雅地失败）。

cache-commit 只是一个锚点名称，它允许应用一些 DRY，并且它使用提交引用名称作为键。