VS Code 扩展巡礼-phpcs

本篇文章中介绍的扩展是 vscode-phpcs，用于项目开发中 PHP 代码的编码规范。

Github 库地址 vscode-phpcs[1].，使用这个扩展依赖于一个前置条件，系统需要安装 PHP_CodeSniffer[2]

phpcs.png

官方是这么介绍这个扩展的https://github.com/shevaua/vscode-phpcs[3]

认识 PHP_CodeSniffer

“PHP_CodeSniffer is an essential development tool that ensures your code remains clean and consistent.

在众多的第三方组织和相关的代码规范推荐中，PHP_CodeSniffer 是一款代码检查工具，用于规范团队开发中的类名，注释，参数等各个方面，帮助团队成员形成统一的编码风格。它本身可以与很多 IDE 结合，也提供了修改和指定自定义代码规范的功能。

PHP_CodeSniffer 包地址 PHP_CodeSniffer[4]Github 库地址 PHP_CodeSniffer[5]

PHP_CodeSniffer 安装

根据操作平台不同，PHP_CodeSniffer 有不同的安装 方式，集中于 Pear，Composer，和 Brew。

Linux 安装方式

pear install PHP_CodeSniffer
whereis phpcs
phpcs: /usr/bin/phpcs

phpcs --version

PHP_CodeSniffer version 3.5.0 (stable) by Squiz (http://www.squiz.net)

Brew 安装

Mac 下采用以下命令安装，最为方便

brew install php-code-sniffer

安装路径

/usr/local/Cellar/php-code-sniffer

/usr/local/Cellar/php-code-sniffer/3.4.1/bin
ls
phpcbf	phpcs

Composer 方式

composer global require squizlabs/php_codesniffer

安装路径

/Users/name/.composer/vendor/squizlabs/php_codesniffer/

ls
phpcbf		phpcbf.bat	phpcs		phpcs.bat

/Users/name/.composer/vendor/bin

文件夹下有两个文件 phpcbf phpcs

运行

./phpcs --version

可以查看版本号

PHP_CodeSniffer version 3.4.2 (stable) by Squiz (http://www.squiz.net)

Mac 下推荐使用 brew 安装 其它安装方式参考 Github 库PHP_CodeSniffer[6]

VS Code 中启用 PHP_CodeSniffer

VS Code 中启用 PHP_CodeSniffer 需要安装 phpcs 插件。

“Before using this plugin, you must ensure that phpcs is installed on your system,The preferred method is using composer[7] for both system-wide and project-wide installations.

也就是说在 VS Code 中使用 phpcs 插件之前，需要在系统上安装有 phpcs，安装方法是依赖于 composer 方式，并且可以从系统级和项目级两个纬度选择安装。

如果只是在 VS Code 中安装插件，系统级中不安装 phpcs。会出现以下错误

phpcs: Request workspace/configuration failed with message: Unable to locate phpcs. Please add phpcs to your global path or use composer dependency manager to install it in your project locally.

还有一点，phpcs 插件只是 CS Code 中实现 PHP CodeSniffer 中的一个，还有很多其它插件也在做基于 PHP CodeSniiffer 的代码整洁优化工作。比如 EasyCodingStandard[8]

系统级全局安装

composer global require squizlabs/php_codesniffer

Changed current directory to /Users/wmm/.composer Using version ^3.4 for squizlabs/php_codesniffer ./composer.json has been updated Loading composer repositories with package information Updating dependencies (including require-dev) Package operations: 1 install, 0 updates, 0 removals

• Installing squizlabs/php_codesniffer (3.4.0): Downloading (100%) Writing lock file Generating autoload files

项目级别的安装

以下是 VS Code 对于插件 phpcs 的介绍说明，更多参考 https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs Project-wide Installation

The phpcs linter can be installed in your project using the Composer Dependency Manager for PHP.

1. Install compose[9].
2. Require phpcs package by typing the following at the root of your project in a terminal:

composer require --dev squizlabs/php_codesniffer

phpcs 与 PHP Sniffer 关系

VS Code 还有另外一个插件 PHP Sniffer。在特性中写着两条

“Runs phpcs to lint PHP code. Runs phpcbf to format fixable PHP code validation errors.`

显然可以推断 PHP Sniffer 也是对 PHP_CodeSniffer 的封装。验证后发现，这个插件可以不使用，phpcs 也可以运行的很好。

VsCode插件巡礼-phpcs-图南科技

VsCode插件巡礼-phpcs-图南科技-php-sniffer.png

如果同时安装 PHP Sniffer 和 phpcs 插件，但是没有安装 PHP_CodeSniffer 会出现以下错误

phpcs: Unable to locate phpcs. Invalid version string encountered!

PHP_CodeSniffer 典型使用

phpcs 目录下运行以下命令

./phpcs -i

The installed coding standards are MySource, PEAR, PSR1, PSR12, PSR2, Squiz and Zend

使用规范

1 方法注释 参数，返回值三项用空行分割。

phpcs.png

2 参数必须有注释，也识别空格，多个参数纵向需要对齐。

对齐.png

3 每一行的代码长度不能超过一定的长度。

最大长度.png

“Line exceeds 85 characters; contains 98 characters

4 私有方法使用下划线 _ 开始。

“Private method name " " must be prefixed with an underscore

关于 PSR

众所周知 PHP 语言是基于开源社区发展起来的，社区可以说又集中又分散，框架，类库数量众多，如何在最大程度上约束代码规范，趋向于统一和标准化，有一个组织在推进这个事情，那就是 FIG Framework Interop Group[10]。

phpcs 这些代码格式化工具也是以 PSR 为理论基础。

The Framework Interop Group[11] has proposed and approved a series of style recommendations.

One recommended way to use namespaces is outlined in PSR-4[12], which aims to provide a standard file, class and namespace convention to allow plug-and-play code.

业界最常用的规范标准成稿是 PSR4，这里 https://phptherightway.com/#code_style_guide[13] 是一篇关于代码规范的概要介绍，可以深入阅读。

总结

VS Code 中对于插件 phpcs 安装方式的介绍，实际上更多是 PHP_CodeSniffer 工具的安装介绍，插件的作用就是帮助项目与 PHP_CodeSniffer 做关联。

搭配 PHP 智能注释 这个插件 会有更完善的使用体验，自动为方法提供注释，再手动做细节调整。

Code Review 是保证团队代码质量的重要措施之一，而代码规范是 Code Review 的重要一环，代码规范又要借助于有效的工具，phpcs 就是这样的工具。

推动代码整洁，高效开发，培养工程师对于代码整洁度的洁癖和质量交付的严格约束。

VS Code插件巡礼-phpcs-图南科技-CodeReview

参考资料

[1]

vscode-phpcs: https://github.com/shevaua/vscode-phpcs

[2]

PHP_CodeSniffer: https://pear.php.net/package/PHP_CodeSniffer/

[3]

https://github.com/shevaua/vscode-phpcs: https://github.com/shevaua/vscode-phpcs

[4]

PHP_CodeSniffer: https://pear.php.net/package/PHP_CodeSniffer/

[5]

composer: https://getcomposer.org/

[6]

EasyCodingStandard: https://marketplace.visualstudio.com/items?itemName=azdanov.vscode-easy-coding-standard

[7]

https://getcomposer.org/doc/00-intro.md: https://getcomposer.org/doc/00-intro.md

[8]

Framework Interop Group: https://www.php-fig.org/

[9]

PSR-4: https://www.php-fig.org/psr/psr-4/

[10]

https://phptherightway.com/#code_style_guide: https://phptherightway.com/#code_style_guide