README

基于 PEAR 和 Zend 编码标准，并结合 PSR-1 和 PSR-2 标准，Zicht 编码标准对这些标准进行了一些自定义规则和修改

文件和类注释不需要强制使用标签。
由于我们不再处于固定宽度控制台的时代，行长度限制被固定为 256，警告长度为 256，错误长度为 512。
define() 调用必须使用文档注释标签。
全局函数名称为 underscored_and_lowercased()，方法名称为 studlyCased。
所有常量，包括全局和类常量都是 UPPERCASED_AND_UNDERSCORED。
不建议使用过多的空白，即超过两行空白和作用域结束前的空白（在闭合括号 '} '之前）会导致警告。
不允许在 use 语句中引用全局命名空间（不能以反斜杠开始）。
不建议为非全局类（不在全局命名空间中的类，即 PHP 核心类）引用全局命名空间。

使用方法

composer require --dev zicht/standards-php

基本使用 vendor/bin/phpcs --standard=vendor/zicht/standards-php/phpcs.xml <directories-and-files>

项目应在其 composer.json 的 scripts 部分中包含以下命令。您应该使用 composer lint 命令在日常工作中检查您提交的代码更改（您还可以将这些检查集成到 PhpStorm 中）。您可以使用 composer lint-fix 命令自动修复可以自动修复的错误。项目应将 composer lint-no-warn 命令实现到其 Q&A 作业中，该作业应在提交新的 pull request 时运行（这将忽略警告，以防止日志中出现大量警告消息，同时测试仍将通过）。

{
    "scripts": {
        "lint": [
            "phpcs --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ],
        "lint-no-warn": [
            "phpcs -n --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ],
        "lint-fix": [
            "phpcbf --standard=vendor/zicht/standards-php/phpcs.xml src/ tests/"
        ]
    }
}

当前规则集

通用

通用.文件.行长度

此规则配置为在超过 256 个字符的行上发出警告，并在超过 512 个字符的行上发出错误（故意不遵循 PSR-2）。您应该修复这些警告，并坚持最大行长度为 256 个字符，但 QA 测试不应因代码行长度超过 256 个字符且小于 512 个字符而失败。

Zicht 检查

本节中解释了 Zicht 集中的每个规则。

一般注释

所有文档块注释嗅探器（类注释、文件注释、函数注释和属性注释）将扫描空文档块和包含多余描述的文档块。只包含多余注释（没有标签）的空文档块必须改进或删除。具有多余描述和标签的文档块的描述必须改进或删除。

通过查看文档块所属的声明，检测到多余的描述，看看它是否是名称的重复，这显然没有增加任何价值。多余的文档块/描述是可自动修复的。

例如，所有三个文档块注释都会因为描述多余而由相关的嗅探器产生错误。

<?php
/**
 * Class SomeExampleClass                   <-- Doc block must be improved or removed
 */
class SomeExampleClass
{
    /**
     * SomeClass constructor.               <-- Doc block must be improved or removed
     */
    public function __construct()
    {
        $this->setSomeValues([1, 2, 3]);
    }

    /**
     * Set some values                      <-- Description must be improved or removed
     *
     * @param int[] $someValues  Integer values to set
     */
    public function setSomeValues(array $someValues)
    {
        $this->someValues = $someValues;
    }
}

Zicht.Commenting.ClassComment

扩展 PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\ClassCommentSniff。此外，检测空或多余的注释（参见 一般注释），并为类文档注释中允许包含的文档块内容添加规则。

不允许在类文档注释中使用 @category、@package、@subpackage、@author 和 @copyright 标签。
文档中的 @version 标签不是必需的，但只允许一个，紧随 @license 后。
文档中的 @link 标签不是必需的，但允许一个或多个。
文档中的 @see 标签不是必需的，但允许一个或多个，紧随 @link 后。
文档中的 @deprecated 标签不是必需的，但只允许一个，紧随 @see（如果使用）或 @version（如果使用）后。

Zicht.Commenting.DefineComment

查找 PHP 中 define 函数之前的注释。

Zicht.Commenting.FileComment

扩展 PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FileCommentSniff。此外，检测空或多余的注释（参见 一般注释），并为文件文档注释中允许包含的文档块内容添加规则。

不允许在文件文档注释中使用 @category、@package、@subpackage 和 @author 标签。
文档中的 @copyright 标签不是必需的，但允许一个或多个。
文档中的 @version 标签不是必需的，但只允许一个，紧随 @license 后。
文档中的 @link 标签不是必需的，但允许一个或多个。
文档中的 @see 标签不是必需的，但允许一个或多个，紧随 @link 后。
文档中的 @deprecated 标签不是必需的，但只允许一个，紧随 @see（如果使用）或 @version（如果使用）或 @copyright（如果使用）后。

Zicht.Commenting.FunctionComment

扩展 \PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FunctionCommentSniff。此外，检测空或多余的注释（参见 一般注释），并检测函数注释中的 {@inheritdoc}，这使得它跳过参数和返回标签的验证（如果没有添加额外的 @param 或 @return）。此外，此嗅探器允许在没有任何参数和返回值或所有参数和返回值都有其类型声明（类型提示）时跳过函数注释。

public function getMeSomeArray(int $id, SomeObject $someObject = null): array
{
    return [];
}

在上面的例子中不需要函数文档注释。

Zicht.Commenting.PropertyComment

此嗅探器检查所需属性注释标记（@var）、它们的（必需）内容和标记的顺序（@var标记必须始终排在第一位，官方PHPDoc标记必须放在其他自定义标记之上。属性注释中不允许有空行，且不允许单独的描述，并且必须与@var标记一起放置。该嗅探器还检测多余的描述（见一般注释）。允许使用单行属性注释（/** @var <type> */）。

Zicht.ControlStructures.ControlSignature

检查某些结构是否符合签名的定义。

do {EOL...} while (...);EOL、while (...) {EOL、for (...) {EOL、if (...) {EOL、foreach (...) {EOL、} else if (...) {EOL、} elseif (...) {EOL、} else {EOL、do {EOL，

例如 do {EOL...} while (...);EOL 表示：do{// (EOL) 从这里开始的行尾 } while ();// (EOL) 从这里开始的行尾。

Zicht.ControlStructures.DisallowAssignments

检测if、elseif、while、foreach和switch控制结构中是否存在任何赋值。默认配置下，最多允许1个赋值，并且它必须位于语句中的其他逻辑之前。

    if ($result = someDataRetrieval() && isset($result['success']) && true === $result['success'])

Zicht.Functions.FunctionCallSignature

此嗅探器覆盖了PEAR Sniff，允许函数调用开括号和数组方括号在同一行上。只有当只有一个参数，并且该参数应该是数组或可以是闭包时，才允许这样做。

Zicht.Methods.FunctionOpeningBrace

检测函数的开括号和第一条代码行之间是否有空行。

Zicht.NamingConventions.Classname

此嗅探器要求类名必须使用CamelCased。

Zicht.NamingConventions.Constants

此嗅探器要求常量名必须使用全部大写（不允许使用小写字母）并且只允许使用A-Z、0-9和下划线。

Zicht.NamingConventions.Functions

此嗅探器定义了命名约定。

类方法必须使用studlyCased或使用lowerCamelCased的替代名称。允许以下方法：construct、get、set、call、callStatic、invoke、destruct、toString、clone、invoke、invokeStatic。在类方法名称中不鼓励使用下划线和数字。数字会创建警告，而下划线会创建错误。

全局函数必须使用snake_cased，即所有小写字母并用下划线分隔。

Zicht.PHP.Namespace

除了全局类之外，命名空间中所有其他类不允许在引用完全限定类名时使用。例如，使用$sniff = new \Zicht\Sniffs\PHP\NamespaceSniff())使用use语句，并按如下格式编写代码：$sniff = new NamespaceSniff();

Zicht.PHP.UseStatement

此嗅探定义了在PHP文件中，use语句应该位于顶部，且只能由declare语句、文档注释或命名空间声明（以及当然的空白等）之前。

Zicht.Whitespace.ExcessiveWhitespace

此嗅探寻找文件中在最后一个}之后的多个空白。

其他规则

要查看此规则集中的规则，您可以从包根目录使用以下命令

vendor/bin/phpcs --standard=Zicht -e

这将生成以下集合

   The Zicht standard contains 67 sniffs

   Generic (15 sniffs)
   -------------------
     Generic.Arrays.DisallowLongArraySyntax
     Generic.ControlStructures.InlineControlStructure
     Generic.Files.ByteOrderMark
     Generic.Files.LineEndings
     Generic.Files.LineLength
     Generic.Formatting.DisallowMultipleStatements
     Generic.Formatting.NoSpaceAfterCast
     Generic.Formatting.SpaceAfterCast
     Generic.Functions.FunctionCallArgumentSpacing
     Generic.Functions.OpeningFunctionBraceBsdAllman
     Generic.NamingConventions.UpperCaseConstantName
     Generic.PHP.DisallowShortOpenTag
     Generic.PHP.LowerCaseConstant
     Generic.PHP.LowerCaseKeyword
     Generic.WhiteSpace.DisallowTabIndent

   PEAR (3 sniffs)
   ---------------
     PEAR.ControlStructures.ControlSignature
     PEAR.Functions.ValidDefaultValue
     PEAR.WhiteSpace.ScopeClosingBrace

   PSR1 (3 sniffs)
   ---------------
     PSR1.Classes.ClassDeclaration
     PSR1.Files.SideEffects
     PSR1.Methods.CamelCapsMethodName

   PSR12 (1 sniff)
   ----------------
     PSR12.Operators.OperatorSpacing

   PSR2 (12 sniffs)
   ----------------
     PSR2.Classes.ClassDeclaration
     PSR2.Classes.PropertyDeclaration
     PSR2.ControlStructures.ControlStructureSpacing
     PSR2.ControlStructures.ElseIfDeclaration
     PSR2.ControlStructures.SwitchDeclaration
     PSR2.Files.ClosingTag
     PSR2.Files.EndFileNewline
     PSR2.Methods.FunctionCallSignature
     PSR2.Methods.FunctionClosingBrace
     PSR2.Methods.MethodDeclaration
     PSR2.Namespaces.NamespaceDeclaration
     PSR2.Namespaces.UseDeclaration

   Squiz (16 sniffs)
   -----------------
     Squiz.Arrays.ArrayDeclaration
     Squiz.Classes.ValidClassName
     Squiz.ControlStructures.ControlSignature
     Squiz.ControlStructures.ForEachLoopDeclaration
     Squiz.ControlStructures.ForLoopDeclaration
     Squiz.ControlStructures.LowercaseDeclaration
     Squiz.Functions.FunctionDeclaration
     Squiz.Functions.FunctionDeclarationArgumentSpacing
     Squiz.Functions.LowercaseFunctionKeywords
     Squiz.Functions.MultiLineFunctionDeclaration
     Squiz.Scope.MethodScope
     Squiz.Strings.DoubleQuoteUsage
     Squiz.WhiteSpace.ControlStructureSpacing
     Squiz.WhiteSpace.ScopeClosingBrace
     Squiz.WhiteSpace.ScopeKeywordSpacing
     Squiz.WhiteSpace.SuperfluousWhitespace

   Zend (2 sniffs)
   ---------------
     Zend.Debug.CodeAnalyzer
     Zend.Files.ClosingTag

   Zicht (15 sniffs)
   -----------------
     Zicht.Commenting.ClassComment
     Zicht.Commenting.DefineComment
     Zicht.Commenting.FileComment
     Zicht.Commenting.FunctionComment
     Zicht.Commenting.PropertyComment
     Zicht.ControlStructures.ControlSignature
     Zicht.Functions.FunctionCallSignature
     Zicht.Methods.FunctionOpeningBrace
     Zicht.NamingConventions.Classname
     Zicht.NamingConventions.Constants
     Zicht.NamingConventions.Functions
     Zicht.PHP.DisallowMultipleAssignmentsInIfStatements
     Zicht.PHP.Namespace
     Zicht.PHP.UseStatement
     Zicht.Whitespace.ExcessiveWhitespace

如上所示，这些规则命名空间被应用。请检查这些命名空间的文档以获取解释。

通用
PEAR
PSR1
PSR2
Squiz
Zend
Zicht

维护者

Boudewijn Schoon boudewijn@zicht.nl
Erik Trapman erik@zicht.nl
Jochem Klaver jochem@zicht.nl

zicht / standards-php

维护者

详细信息