README

Joomla项目已将其所有代码迁移到使用PSR-12代码风格，而不是自定义版本。如果您正在使用此代码风格，也应迁移到PSR-12。此代码风格将不再维护，因此自2024年3月起已存档。

cms-coding-standards

用于Joomla CMS环境的扩展Joomla编码规范定义

此存储库包含Joomla CMS编码规范定义，用于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.9+ 或
• PHP 5.6+
• PHP Codesniffer 3.3.0+

通过Composer安装

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

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

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

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

运行

您可以使用已安装的Joomla标准，例如

phpcs --standard=Joomla-CMS path/to/code

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

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

选择性应用规则

注意：这应该是主Joomla编码规范README中“选择性应用规则”部分的精确副本，这里只供参考

对于消费包，有些项目通常会导致创建自己的project_ruleset.xml，而不是直接使用Joomla的ruleset.xml。项目ruleset.xml允许编码规范有选择性地应用于排除第三方库、考虑现有项目的向后兼容性，或者对不需要php 5.3兼容性的项目进行调整（这将随着所有活动Joomla项目中php 5.3支持的结束而在未来版本的Joomla编码规范中删除）。

有关选择性应用规则的详细信息，请参阅PHP CodeSniffer维基百科

常见的规则集调整

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

<!-- 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项目中已被弃用，但由于B/C原因仍存在于项目中。因此，排除MethodUnderscore嗅探是常见的规则集调整。

 <rule ref="Joomla">
  <exclude name="Joomla.NamingConventions.ValidFunctionName.MethodUnderscore"/>
  <exclude name="Joomla.NamingConventions.ValidVariableName.ClassVarHasUnderscore"/>
 </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 [路径_1],[路径_2],[/path/to/joomla-coding-standards],[/path/to/joomla/coding-standards/Example-Rulesets]