README

此包定义了 CiviCRM 编码规范。

CiviCRM 编码规范基于 Drupal 的编码规范，但做了一些修改和放宽。更多详情请见 https://docs.civicrm.org/dev/en/latest/standards/php/。

历史上，CiviCRM 的编码规范一直保存在本存储库中 Drupal 编码规范分支的派生版本中的 8.x-2.x-civi：https://github.com/civicrm/coder。

这勉强可行，但有一些缺点，其中之一就是我们正在篡改 Drupal 编码规范的 'namespace'，即你通常必须运行类似 phpcs --standard==Drupal CRM/Core/Action.php 的命令。

此包定义了自己的标准 CiviCRM，因此你可以运行 phpcs --standard==CiviCRM CRM/Core/Action.php。

安装

你可以选择全局安装 CiviCRM 编码规范（例如，使用 composer global require）或者作为项目的一部分本地安装。

全局安装

可以使用 composer global require michaelmcandrew/civicrm-coding-standards 全局安装 CiviCRM 的编码规范。

现在 - 假设你的 composer 全局 bin 目录（例如 $HOME/.config/composer/vendor/bin）已经添加到你的 $PATH 中 - 你现在应该能够运行 phpcs -i 并看到 CiviCRM 列为可用标准。

你可以通过在最新的 CiviCRM 版本上运行 phpcs --standard=CiviCRM CRM/Core/Action.php 来快速检查标准是否正常工作。如果没有输出，则表示没有违反代码规范。

本地安装

可以使用类似的方法使用本地安装 CiviCRM 的编码规范。

从你的项目目录中，运行 composer require michaelmcandrew/civicrm-coding-standards。

你现在应该能够运行 vendor/bin/phpcs -i 并看到 CiviCRM 列为可用标准。运行 vendor/bin/phpcs --standard=CiviCRM example.php 将在该文件上运行编码规范。

开发安装

如果你想要测试开发标准，可以利用 composer 的 'path repositories' 功能。以下是一个全局 composer 配置示例，展示了如何进行此操作。

{
  "$schema": "https://getcomposer.org.cn/schema.json",
  "require": {
    "michaelmcandrew/civicrm-coding-standards": "^1.1.1"
  },
  "minimum-stability": "dev",
  "repositories": [
    {
      "type": "path",
      "url": "/home/michael/src/civicrm-coding-standards"
    }
  ]
}

用法

phpcs --standard=CiviCRM example.php 将检查 example.php 是否符合 CiviCRM 编码规范。

你还可以创建一个配置文件，例如 .phpcs.xml，告诉 phpcs 你想要使用哪个标准。phpcs 会检查当前目录及其所有父目录以查找用于 linting 的配置文件。

以下是一个应用 CiviCRM 编码规范示例文件：

<?xml version="1.0"?>
<ruleset>
  <rule ref="CiviCRM" />
</ruleset>

测试

bin/analyse.php 脚本从 phpcs 获取 json 输出，并按失败的次数对 sniffs 进行排序。这可能有助于确定我们需要做什么才能将失败的 sniffs 数量降至 0。

以下是如何使用它的示例（根据实际情况更改路径）。

1. 从 civicrm 代码库的根目录运行 phpcs --report=json --standard=CiviCRM . > ~/report.json
2. cat ~/report.json | php ~/src/civicrm-coding-standards/bin/analyse.php

例如。

Array
(
    [Drupal.WhiteSpace.ScopeIndent.IncorrectExact] => 18213
    [Squiz.Functions.MultiLineFunctionDeclaration.SpaceAfterFunction] => 2837
    [Drupal.Classes.ClassFileName.NoMatch] => 2279
    [Drupal.Commenting.VariableComment.Missing] => 1749
    [Generic.PHP.UpperCaseConstant.Found] => 1734
    [Drupal.Arrays.DisallowLongArraySyntax.Found] => 1140
    [SlevomatCodingStandard.PHP.ShortList.LongListUsed] => 613
    [Drupal.Commenting.ClassComment.Short] => 501
    [Drupal.Commenting.Deprecated.IncorrectTextLayout] => 455
    [Drupal.Commenting.Deprecated.DeprecatedMissingSeeTag] => 441
    [Drupal.Commenting.TodoComment.TodoFormat] => 427

    ...more failures here...

    [Squiz.WhiteSpace.SuperfluousWhitespace.StartFile] => 1
    [Squiz.PHP.NonExecutableCode.ReturnNotRequired] => 1
    [Generic.PHP.DeprecatedFunctions.Deprecated] => 1
    [PEAR.Files.IncludingFile.BracketsNotRequired] => 1
    [Squiz.Arrays.ArrayDeclaration.SpaceInEmptyArray] => 1
)