代码提交规范检查与修复 php_codesniffer + composer-git-hooks

Sparkfly 的个人博客 / 4 / 0 / 创建于 4年前 / 更新于 2年前

PSR-1 基础代码规范

PHP 代码文件必须以 <?php 或 <?= 标签开始；
PHP 代码文件必须以不带 BOM 的 UTF-8 编码；
PHP 代码中应该只定义类、函数、常量等声明，或其他会产生 副作用 的操作（如：生成文件输出以及修改 .ini 配置文件等），二者只能选其一；
命名空间以及类必须符合 PSR 的自动加载规范：PSR-0（已废弃）或 PSR-4 中的一个。
类的命名必须遵循 StudlyCaps 大写开头的驼峰命名规范；
类中的常量所有字母都必须大写，单词间用下划线分隔；
方法名称必须符合 camelCase 式的小写开头驼峰命名规范。

PSR-2 编码风格指南

代码必须遵循 PSR-1 中的编码规范。
代码必须使用 4 个空格符而不是「Tab 键」进行缩进。
每行的字符数应该软性保持在 80 个之内，理论上一定不可多于 120 个，但一定不可有硬性限制。
每个 namespace 命名空间声明语句和 use 声明语句块后面，必须插入一个空白行。
类的开始花括号 { 必须写在函数声明后自成一行，结束花括号 } 也必须写在函数主体后自成一行。
方法的开始花括号 { 必须写在函数声明后自成一行，结束花括号 } 也必须写在函数主体后自成一行。
类的属性和方法必须添加访问修饰符 private 、protected 以及 public ，abstract 以及 final 必须声明在访问修饰符之前，而 static 必须声明在访问修饰符之后。
控制结构的关键字后必须要有一个空格符，而调用方法或函数时则一定不可有。
控制结构的开始花括号 { 必须写在声明的同一行，而结束花括号 } 必须写在主体后自成一行。
控制结构的开始左括号后和结束右括号前，都一定不可有空格符。

代码提交规范检查与修复

开始之前，我们需要安装 Composer 依赖：

composer require squizlabs/php_codesniffer --dev
composer require brainmaestro/composer-git-hooks --dev

扩展 php_codesniffer 包含两个脚本 phpcs 和 phpcbf，phpcs 脚本用于检测和标记违反定义的编码标准的情况，phpcbf 脚本用于自动纠正编码标准冲突。

尝试手工检查项目编码风格情况(下面的例子是以 Laravel6 项目为例的):

phpcs --standard=PSR1,PSR2 app/ routes/ config/

# 这个命令运行应该会出现异常 zsh: command not found: phpcs
# 因为全局环境并没有 phpcs 命令，修改为：

./vendor/bin/phpcs --standard=PSR1,PSR2 app/ routes/ config/
# 命令正常执行

我们测试编辑一下，比如在 IndexController.php namespace 下一行空格去掉，再次执行检查命令：

./vendor/bin/phpcs --standard=PSR1,PSR2 app/ routes/ config/

# FILE: /xxx/Controllers/IndexController.php
# ------------------------------------------------------------------------------------
# FOUND 1 ERROR AFFECTING 1 LINE
# ------------------------------------------------------------------------------------
#  3 | ERROR | [x] There must be one blank line after the namespace declaration
# ------------------------------------------------------------------------------------
# PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
# ------------------------------------------------------------------------------------
# Time: 217ms; Memory: 8MB

发现检查提示 There must be one blank line after the namespace declaration，编码风格 namespace 后必须空一行。

尝试自动纠正脚本 phpcbf

./vendor/bin/phpcbf --standard=PSR1,PSR2 app/ routes/ config/
# 和 phpcs 命令一样，我们需要指定命令所在目录

运行后，我们可以发现 namespace 后新增一空白行，表示脚本已经正常执行了。

追求更高效的方式，每次都手工键入命令./vendor/bin/phpcs --standard=PSR1,PSR2 app/ routes/ config/ Modules/ 和 ./vendor/bin/phpcbf --standard=PSR1,PSR2 app/ routes/ config/ 参数太多，记不住！不靠谱！

写个别名：

"scripts": {
    "lint": "phpcs --standard=PSR1,PSR2,./ruleset.xml app/ routes/ config/ Modules/",
    "lint-fix": "phpcbf --standard=PSR1,PSR2 app/ routes/ config/ Modules/"
}

运行命令变更为：

composer run lint
composer run lint-fix

开始配置 pre-commit hook

修改 composer.json 文件，添加 hooks

"extra": {
    "hooks": {
        "pre-commit": [
            "echo committing as $(git config user.name).",
            "composer run lint"
        ]
    }
}

还不能生效，需要手动执行 ./vendor/bin/cghooks update，如果希望每次更新 composer.json 都执行 cghooks 更新，可以利用 composer event 事件 post-autoload-dump，如添加下面代码：

"scripts": {
    "post-autoload-dump": [
        "cghooks update"
    ],
}

注意：初次使用 composer install --no-dev 时，cghooks 会出现异常。

再次执行 composer install 就可以触发事件：

composer install

> cghooks update
Updated pre-commit hook

到这里就完成 pre-commit hook 自动检查编码风格了，马上提交一次修改：

➜  php-project git:(master) ✗ git commit -am 'feat: 新增 phpcs 检查 phpcbf 格式化'
git config user.name =>  xxxx.
> phpcs --standard=PSR1,PSR2 app/ routes/ config/ Modules/
...

检查存在违反编码风格定义，就会终止提交并提示错误信息。好！修改正确后再提交。

自定义验证规则

项目根目录下创建文件 ruleset.xml，定义你想要的规则

github.com/squizlabs/PHP_CodeSniff...

<?xml version="1.0"?>
<ruleset name="Custom">
    <description>Zend, but without linelength check.</description>
    <!-- Warn about lines longer than 135 chars, and never error. -->
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="135" />
            <property name="absoluteLineLimit" value="0" />
        </properties>
    </rule>
</ruleset>

然后，修改 phpcs 命令，追加自定义规则参数 phpcs --standard=PSR1,PSR2,./ruleset.xml app/ routes/ config/ Modules/即可。

IDE 配置 PhpStorm 编码格式检查与格式化

设置 Code Sniffer 编码风格检查，异常提示

第一步，打开配置： Preferences => Language & Frameworks =>PHP => Code Sniffer

点击 Configuration 配置，并指定 PHP Code Sniffer (phpcs) Path ：为你自己本地路径，如项目地址 project/vendor/bin/phpcs，或者你可以全局安装 php_codesniffer, 这样就指定 /Users/yourhome/.composer/vendor/bin/phpcs

composer global require squizlabs/php_codesniffer

第二步，打开配置：Preferences => Editor => Inspections => PHP => PHP Code Sniffer validation

选择勾上 PHP Code Sniffer validation 配置项，配置 Coding Standard 编码标准下拉选中 PSR2

第三步，修改文件验证风格检查

违反规则时可以看到 phpcs 提示信息。

设置自动纠正格式化文件

第一步，打开配置： Preferences => Tools =>External Tools

点击新增 php-cs-fixer 工具

Program 配置: /Users/yourhome/.composer/vendor/bin/phpcbf
Arguments 配置：--standard=PSR1,PSR2 $FileDir$/$FileName$
Working directory 配置： $ProjectFileDir$