README

此包与 phpcs 兼容，并对 Loadsys 使用的编码标准进行检查。它基于 CakePHP 编码标准，并进行了一些针对 Loadsys 内部标准和偏好的定制。

⚠️ 此代码设计用于针对 Cake 3.x 项目，对于 Cake 2.x 项目，请使用此项目最新的 2.x 版本之一。

显著的样式差异

此规则集基本上是 PSR-2，但有以下差异

缩进使用制表符而不是空格。在文件大小和打字速度方面，1 个字符比 4 个空格要好。其他关于“细粒度对齐”的论点是对编辑工具的失败，而不是制表符本身的问题。回到空格是错误的解决方案。 (参见弹性制表符.)
开括号通常位于其代码块开头同一行上。这适用于类、函数、方法和所有控制结构。我们更喜欢单一一致的大括号规则。
多行数组中的最后一个逗号是强制性的。这使得差异更干净，并在重新排序列表时减少了错误。

所有类必须在文件顶部声明，然后才能使用。

 $var = new \DateTime(); // invalid
 $var = new \Vendor\Lib(); // invalid
 $var = new Local\SubClass(); // invalid
 //---
 use \DateTime
 $var = new DateTime(); // valid

其他继承但仍值得指出的事项

类必须使用命名空间。
短数组语法是强制性的。

安装

使用 composer 在您的项目中安装这些代码检查器

$ composer require loadsys/loadsys_codesniffer:~3.0
$ vendor/bin/phpcs --config-set installed_paths vendor/cakephp/cakephp-codesniffer,vendor/loadsys/loadsys_codesniffer

第二个命令让 phpcs 知道在哪里找到 Loadsys 和 CakePHP 检查器。如果您有其他自定义 PHPCS 检查器位置，请确保不要覆盖任何现有的 installed_paths 值。

用法

一旦配置了 installed_paths，您就可以使用以下命令运行 phpcs：

$ bin/phpcs -p --standard=Loadsys

警告当这些检查器通过 composer 安装时，请确保您已为 CakePHP 标准和 Loadsys 标准都设置了 CodeSniffer 的 installed_paths 设置。

一个典型的选项是在 Travis 上运行时抑制警告。为此，请使用 -n CLI 选项。

$ bin/phpcs -n --standard=Loadsys

贡献

克隆项目并创建一个新的功能分支。
运行 composer install 以安装项目的测试依赖项。
根据需要创建/编辑 Loadsys/Sniffs/* 类或修改 Loadsys/ruleset.xml。
在 snifftests/files/ 中添加或更改源文件，以验证新/更改规则的成功/失败状态。
运行 vendor/bin/phpunit 以确认所有测试都通过。
提交一个 PR。

注意： 当根目录包含短横线时，phpunit 将无法运行测试。（因此使用 loadsys_codesniffer 而不是 loadsys-codesniffer。）

发布 Loadsys 代码检查器

审查并合并 PR。
创建 git 标签。
将标签推送到仓库。（Packagist 将被通知。）

测试

测试是在使用设计为要么通过整个检查器套件而不会产生任何错误或警告的样本文件，要么旨在失败并触发特定检查器错误/警告的编码标准上运行的。

这些示例文件位于snifftests/files/目录中，可以根据任何合理的方式进行分组。我们选择将测试分为两个强制性的文件夹，即must/和must_not/。文件名以正在测试的主题开头，例如array_、braces_或indent_，然后继续使用更具体的内容。例如

snifftests/files/must_not/array_syntax_long.php
snifftests/files/must/array_syntax_short_pass.php

测试可以确认编码错误是否被嗅探器正确捕获，或者有效编码实践是否被嗅探器错误捕获。

参考嗅探规则

由于我们继承自这些规则集，因此方便地链接到它们是件好事

CakePHP: ruleset.xml，Sniffs
PSR-2: ruleset.xml，Sniffs
所有Squiz提供的标准
Vanilla Forums: ruleset.xml，Sniffs（我们使用他们的“ValidClassBrackets”嗅探器的副本。）
Codesniffer文档: Annotated ruleset.xml

在Loadsys定义的嗅探类上运行codesniffs

vendor/bin/phpcs -ps --standard=snifftests/sniff_class_rules.xml Loadsys/

此自定义规则集放宽了我们的一些正常规则，以适应PHPCS对嗅探类本身的要求的不足（例如不支持命名空间或驼峰式类名。）该规则集将运行整个Loadsys标准，排除那些规则。

审查标准中包含的规则

vendor/bin/phpcs -e --standard=./Loadsys Loadsys

此列表可用于帮助定位在Loadsys/ruleset.xml中直接定义的重复规则。

运行测试

# Run once:
$ composer install
$ vendor/bin/phpcs --config-set installed_paths vendor/cakephp/cakephp-codesniffer

# Run repeatedly:
$ vendor/bin/phpunit

指出预期的嗅探失败

snifftests/files/目录内所有不以pass.php结尾的文件都预期至少失败一个代码嗅探。预期失败的嗅探器的名称必须注释在文件的第一个行上，如下所示

		<?php //~Standard.Section.Sniff.Rule,Second.Rule.To.Expect
		$a = [1 , 2]; // Error: Space before comma.

测试套件将为任何缺少*pass.php且未定义预期嗅探失败（如上所示）的文件抛出断言失败。

应尽可能限制预期失败的每个示例文件仅触发单个嗅探。（当前测试方法的不足之处在于我们可以验证命名的嗅探器失败，但不能验证在此过程中没有抛出其他嗅探器。）

指出预期的嗅探通过

后缀为pass.php的文件预期将通过所有嗅探。它们不能在内容的第一个行上使用<?php //~语法定义任何预期的嗅探名称作为失败，否则将抛出PHPUnit断言并中止整个测试套件。

积极的验证测试在修改编码标准规则集时尤为重要。这可以防止意外开始禁止之前可以接受的行为，并有一个验证该“可接受”行为的示例。

手动审查测试/规则

要测试单个示例文件，请运行

$ vendor/bin/phpcs -ps --standard=./Loadsys snifftests/files/sample_file_name.php

要确认所有应通过的测试文件确实通过了，请运行

$ find snifftests/files -type f -name '*pass.php' -exec vendor/bin/phpcs -p --standard=./Loadsys {} +

要确认所有应失败的文件确实失败了，请运行

$ find snifftests/files -type f -name '*.php' ! -name '*pass.php' -exec vendor/bin/phpcs -p --standard=./Loadsys {} +

列出的每个文件都应该至少抛出一个警告或错误。请注意初始进度指示器中的任何 .，因为这表示完全通过的文件，而该文件应该有某些失败的地方！列出的错误需要手动验证，以确保它们正确地匹配特定文件应该触发的错误。

许可证

MIT

版权

Loadsys Web Strategies 2016

loadsys / loadsys_codesniffer

维护者

详情