README

从 Joomla 版本 4.2 开始，Joomla 使用 PSR-12 编码标准。

我们将很快更新以反映这一变化

所有非 PHP 编码标准仍然有效

Joomla 编码标准

此存储库包含 Joomla 编码标准定义，用于 PHP Codesniffer，以及一些其他有用的资源。PHP_CodeSniffer 标准永远不会达到 100% 准确，但在为 Joomla 编写软件时应将其视为一套强大的指南。

有关 Joomla 编码标准的文档，请参阅 https://developer.joomla.net.cn/coding-standards.html

如果您想贡献并改进此文档，可以在 master 分支的手册部分找到源文件 https://github.com/joomla/coding-standards/tree/master/manual

要求

• PHP 5.3+
• PHP Codesniffer 2.8+

重要提示：目前最新的 PHPCS 是 3.x 系列。有一个 开发分支 用于与 PHPCS 3.x 系列兼容的 Joomla 自定义 sniffs。尽管 PEAR 和 composer 提供了安装 PHPCS 3.x 的选项，但 Joomla 自定义 sniffs 的发布目前仅兼容 PHPCS 2.x，并且不会正常工作，因此我们提醒您，如果您使用的是 Joomla 自定义 sniffs，请始终安装 PHPCS 2.x 系列。如果您想测试 Joomla 编码标准 PHPCS 3.x 开发分支，请手动安装 3.x 分支。

通过 Composer 安装

将 "joomla/coding-standards": "~2.0" 添加到 composer.json 中的 require-dev 块，然后运行 composer install。

{
    "require-dev": {
		"joomla/coding-standards": "~2.0"
	}
}

或者，您可以直接从命令行运行以下操作

composer global require squizlabs/php_codesniffer "~2.8"
composer require joomla/coding-standards "~2.0"

由于 joomla/coding-standards 2.0.0 的稳定性目前处于 alpha 阶段，请确保您已在 Composer 中允许使用 alpha 软件版本：在 Composer json 中

{
    "require-dev": {
		"joomla/coding-standards": "~2.0@alpha"
	}
}

或在命令行中

composer config minimum-stability "alpha"

如果您想全局安装编码标准，通过运行以下命令编辑您的 Composer 全局配置：

composer global config -e

并添加以下内容："minimum-stability": "alpha"

一旦您有了编码标准文件，您可以告诉 PHPCS 标准文件夹的位置（即在 PHPCS 中安装它们）

phpcs --config-set installed_paths /path/to/joomla-coding-standards

注意：当标准全局安装时，将运行 composer 脚本，但当它是依赖项时不会运行。因此，您可能需要运行 phpcs config-set。当您运行 phpcs config-set 时，它将始终覆盖先前的值。使用 --config-show 检查在使用 --config-set 之前的值。因此，您应该使用 --config-show 揭示的现有路径复制现有路径，并按逗号分隔添加每个路径：phpcs --config-set installed_paths [path_1],[path_2],[/path/to/joomla-coding-standards]

运行

您可以使用安装的 Joomla 标准如下

phpcs --standard=Joomla path/to/code

或者，如果没有安装，您也可以通过路径引用它

phpcs --standard=path/to/joomla/coding-standards path/to/code

选择性应用规则

对于消费包，有些项目通常会产生自己的 project\ruleset.xml 文件，而不是直接使用 Joomla 的 ruleset.xml。项目 ruleset.xml 允许有选择性地应用编码标准，用于排除第三方库、考虑现有项目的向后兼容性，或者为不需要 PHP 5.3 兼容性的项目进行调整（PHP 5.3 兼容性将在 Joomla 编码标准的未来版本中随着所有活跃的 Joomla 项目对 PHP 5.3 支持的结束而移除）。

有关选择性应用规则的信息，请阅读 PHP CodeSniffer wiki 中的详细内容选择性应用规则

常见的规则集调整

最常见的调整是排除包含第三方库的文件夹，或者代码尚未应用编码标准的文件夹。

 <!-- Exclude folders not containing production code -->
 <exclude-pattern type="relative">build/*</exclude-pattern>
 <exclude-pattern type="relative">tests/*</exclude-pattern>

 <!-- Exclude 3rd party libraries. -->
 <exclude-pattern type="relative">libraries/*</exclude-pattern>
 <exclude-pattern type="relative">vendor/*</exclude-pattern>

另一种常见的调整是排除“类、函数、方法、常规变量和类属性”的 camelCase 格式要求，这实际上允许与数据库交互的上下文中使用 snake_case 变量。

 <rule ref="Joomla">
  <exclude name="Joomla.NamingConventions.ValidFunctionName.ScopeNotCamelCaps"/>
  <exclude name="Joomla.NamingConventions.ValidVariableName.NotCamelCaps"/>
  <exclude name="Joomla.NamingConventions.ValidVariableName.MemberNotCamelCaps"/>
  <exclude name="Joomla.NamingConventions.ValidFunctionName.FunctionNoCapital"/>
 </rule>

旧的保护方法名曾经以下划线为前缀。这些带有下划线的保护方法名在 Joomla 项目中已弃用，但出于向后兼容性的原因仍然存在于项目中。因此，排除 MethodUnderscore 代码嗅探是一个常见的规则集调整。

 <rule ref="Joomla">
  <exclude name="Joomla.NamingConventions.ValidFunctionName.MethodUnderscore"/>
  <exclude name="Joomla.NamingConventions.ValidVariableName.ClassVarHasUnderscore"/>
 </rule>

最后最常见的调整是移除针对 PHP 5.3 的特定规则，这些规则阻止了短数组语法，并允许方法参数使用短数组语法。

 <rule ref="Generic">
  <exclude name="Generic.Arrays.DisallowShortArraySyntax"/>
 </rule>
 <rule ref="Joomla.Classes.InstantiateNewClasses">
   <properties>
     <property name="shortArraySyntax" value="true"/>
   </properties>
 </rule>
 

使用选择性应用规则的示例规则集

您需要告诉 PHPCS 示例规则集文件夹的位置（即，在 PHPCS 中安装它们）

phpcs --config-set installed_paths /path/to/joomla/coding-standards/Example-Rulesets

注意：当标准全局安装时，composer 脚本将运行，但当它是依赖项时不会运行。因此，您可能想要运行 PHPCS config-set。当您运行 PHPCS config-set 时，它将始终覆盖先前值。使用 --config-show 检查在使用 --config-set 之前的先前值。因此，而不是覆盖现有路径，您应该使用 --config-show 显示的现有路径进行复制，并按逗号分隔每个路径：phpcs --config-set installed_paths [path_1],[path_2],[/path/to/joomla-coding-standards],[/path/to/joomla/coding-standards/Example-Rulesets]

IDE 自动格式化器

有关如何设置 IDE 自动格式化器的更多信息，请参阅此处

https://github.com/joomla/coding-standards/tree/master/Joomla/IDE