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

PSR-1 基础代码规范

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

PSR-2 编码风格指南

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

代码提交规范检查与修复

开始之前,我们需要安装 Composer 依赖:

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

扩展 php_codesniffer 包含两个脚本 phpcsphpcbfphpcs 脚本用于检测和标记违反定义的编码标准的情况,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 就可以触发事件:

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$

本作品采用《CC 协议》,转载必须注明作者和本文链接
Sparkfly
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
讨论数量: 0
(= ̄ω ̄=)··· 暂无内容!

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!