本文针对php和html代码的自动化格式化需求，介绍了php-cs-fixer作为clang-format的有效替代方案。它不仅能检查代码规范，还能自动修复常见问题，并支持自定义规则集，是实现持续集成(ci)中代码风格一致性检查的理想工具。
在软件开发过程中，代码风格的一致性对于提高代码可读性、降低维护成本以及促进团队协作至关重要。对于C/c++/Objective-C等语言，clang-format是一款广受认可的自动化代码格式化工具。然而，当涉及到PHP和html代码时，开发者需要寻找类似的工具来确保代码风格的统一性。本文将深入探讨如何利用PHP-CS-Fixer这一强大工具，实现PHP和HTML代码的自动化格式化和规范检查。
1. PHP-CS-Fixer简介
PHP-CS-Fixer是一款由symfony社区维护的PHP代码风格修复工具。它能够根据预定义的或自定义的规则集，自动检查并修复PHP代码中的各种风格问题。尽管其名称侧重于PHP，但由于PHP文件通常会嵌入HTML，PHP-CS-Fixer也能在一定程度上处理包含HTML的PHP文件，确保整体代码的整洁。
核心优势：
- 自动化修复： 不仅仅是报告问题，它还能自动修复许多常见的代码风格违规。
- 高度可配置： 支持使用现有的PSR（PHP Standard Recommendation）标准规则集，也允许用户创建和定制自己的规则集。
- CI/CD友好： 易于集成到持续集成/持续部署(CI/CD)流程中，作为代码提交或拉取请求(Pull Request)的门禁检查。
2. 安装与基本使用
PHP-CS-Fixer推荐通过composer进行安装。
立即学习“PHP免费学习笔记（深入）”；
安装步骤：
-
全局安装（不推荐，但可行）：
composer global require friendsofphp/php-cs-fixer
然后确保Composer的bin目录在您的PATH中。
-
项目局部安装（推荐）：
composer require --dev friendsofphp/php-cs-fixer
这会将PHP-CS-Fixer安装到项目的vendor/bin目录下。
基本使用命令：
安装完成后，您可以通过以下命令运行PHP-CS-Fixer：
-
检查文件（不修改）：
./vendor/bin/php-cs-fixer fix <path/to/your/file.php> --dry-run --diff
–dry-run 选项表示只检查不修改，–diff 会显示建议的修改内容。
-
修复文件：
./vendor/bin/php-cs-fixer fix <path/to/your/file.php>
-
检查并修复整个目录：
./vendor/bin/php-cs-fixer fix <path/to/your/directory>
3. 配置规则集
PHP-CS-Fixer的强大之处在于其灵活的规则配置。您可以通过在项目根目录创建.php-cs-fixer.dist.php文件来定义您的代码风格规则。
示例 .php-cs-fixer.dist.php 配置：
<?php $finder = PhpCsFixerFinder::create() ->in(__DIR__) // 扫描当前目录及其子目录 ->exclude('vendor') // 排除vendor目录 ->name('*.php') // 只处理.php文件 ->ignoreDotFiles(true) // 忽略点文件 ->ignoreVCS(true) // 忽略版本控制文件 ; return (new PhpCsFixerConfig()) ->setRules([ '@PSR12' => true, // 启用PSR-12标准的所有规则 'array_syntax' => ['syntax' => 'short'], // 数组使用短语法 [] 'ordered_imports' => ['sort_algorithm' => 'alpha'], // 导入语句按字母顺序排序 'single_line_comment_style' => ['comment_types' => ['hash']], // 单行注释使用//而不是# 'whitespace_after_comma_in_array' => true, // 数组逗号后有空格 'no_unused_imports' => true, // 移除未使用的use语句 'phpdoc_add_missing_param_annotation' => ['only_untyped' => false], // 自动添加缺失的@param注解 'strict_comparison' => true, // 强制使用严格比较 === 和 !== 'strict_param' => true, // 强制函数参数类型声明 // 更多规则... ]) ->setFinder($finder) ->setCacheFile(__DIR__.'/.php-cs-fixer.cache') // 设置缓存文件，提高性能 ->setRiskyAllowed(true) // 允许可能改变代码行为的“危险”规则 ;
在这个配置文件中：
- PhpCsFixerFinder 用于定义哪些文件和目录应该被扫描。
- setRules() 方法用于指定要应用的具体规则。@PSR12 是一个预设的规则集，包含了遵循PSR-12标准的所有规则。您还可以添加或覆盖单个规则。
- setCacheFile() 可以设置一个缓存文件，避免每次运行时都重新分析所有文件，从而提高执行速度。
- setRiskyAllowed(true) 允许使用一些可能改变代码行为的规则（例如，某些类型转换规则），使用时需谨慎。
4. CI/CD集成
将PHP-CS-Fixer集成到CI/CD流程中是确保代码质量的关键一步。通常，这会在代码被合并到主分支之前，作为拉取请求（Pull Request）检查的一部分。
集成示例（以gitHub Actions为例）：
您可以在项目的.github/workflows目录下创建一个YAML文件，例如php-cs-fixer.yml。
name: PHP-CS-Fixer on: pull_request: branches: [ "main", "master" ] push: branches: [ "main", "master" ] jobs: php-cs-fixer: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 with: # 允许PHP-CS-Fixer在需要时自动提交修复 # fetch-depth: 0 # 如果需要PHP-CS-Fixer自动提交修复，则取消注释 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.2' # 根据您的项目需求设置PHP版本 extensions: mbstring, xml, ctype, iconv, intl, pdo_sqlite tools: composer:v2 - name: Install dependencies run: composer install --prefer-dist --no-progress --no-suggest - name: Run PHP-CS-Fixer run: | ./vendor/bin/php-cs-fixer fix --dry-run --diff --verbose # 如果PHP-CS-Fixer发现任何问题，则此步骤将失败，从而阻止合并拉取请求。 # 如果您希望PHP-CS-Fixer自动修复并提交，可以修改此步骤，但这通常不推荐在CI中直接修改代码。
在这个github Actions配置中：
- 当有拉取请求或推送到main/master分支时，工作流将被触发。
- 它会检出代码，设置PHP环境并安装Composer依赖。
- 最后，运行php-cs-fixer fix –dry-run –diff –verbose命令。如果发现任何代码风格问题，–dry-run会确保不会修改文件，但会以非零退出码结束，从而使CI检查失败，阻止不符合规范的代码合并。
5. 注意事项与最佳实践
- 逐步引入： 对于现有的大型项目，一次性应用所有规则可能导致大量更改。建议逐步引入规则，或仅针对新代码启用严格检查。
- 团队协作： 确保团队所有成员都使用相同的PHP-CS-Fixer版本和相同的.php-cs-fixer.dist.php配置文件。将其纳入版本控制是基本要求。
- 编辑器集成： 许多现代ide（如VS Code、phpstorm）都支持集成PHP-CS-Fixer，可以在保存文件时自动运行，提供即时反馈。
- 性能： 对于非常大的项目，可以通过调整Finder的配置（如排除更多目录、限制文件类型）或使用–path-mode=intersection来优化性能。
总结
PHP-CS-Fixer是PHP和HTML代码自动化格式化和规范检查的理想工具，它为开发者提供了一个强大且灵活的解决方案，以保持代码风格的一致性。通过合理的配置和与CI/CD流程的集成，团队可以有效地在开发早期捕获并修复代码风格问题，从而提升整体代码质量和开发效率。