本文旨在解决php和html代码的自动化格式化问题，特别是在持续集成(ci)环境中的应用。针对c/c++/objective-c的clang-format，我们推荐使用php-cs-fixer作为php代码的强大替代方案。它不仅能检查代码标准，还能自动修复格式问题，并通过高度可配置的规则集确保团队代码风格的一致性，从而提升代码质量和协作效率。
1. 引言：代码格式化与持续集成
在软件开发过程中，代码格式的一致性对于团队协作、代码可读性和维护性至关重要。clang-format是C/C++/Objective-C等语言领域广受欢迎的自动化代码格式化工具，它能够确保代码风格的统一。然而，对于PHP和HTML等Web开发常用语言，开发者往往需要寻找类似的工具来解决自动化格式化的问题。特别是在持续集成（CI）流程中，例如通过Pull Request提交代码时，自动检查并强制执行代码格式规范，是提升代码质量和减少人工审查负担的有效手段。
本文将探讨PHP和HTML代码的自动化格式化方案，并重点介绍一个功能强大且广泛应用于PHP生态系统的工具——PHP-CS-Fixer，以及如何在CI环境中集成它。
2. 推荐方案：PHP-CS-Fixer
对于PHP代码的自动化格式化，我们强烈推荐使用 PHP-CS-Fixer。尽管其名称侧重于PHP，但它能够处理包含PHP代码的混合HTML文件，并且可以通过配置来忽略纯HTML部分，或者与其他HTML格式化工具（如Prettier等）配合使用。
PHP-CS-Fixer是一个由Symfony项目支持的工具，它不仅是一个代码标准检查器，更是一个强大的代码修复器。它可以根据预定义的或自定义的规则集自动修复代码中的格式问题，从而确保代码库的风格统一。
立即学习“PHP免费学习笔记（深入）”；
3. PHP-CS-Fixer核心特性
PHP-CS-Fixer具备以下关键特性，使其成为PHP项目代码格式化的理想选择：
- 代码标准检查与修复： 能够识别违反编码标准（如PSR-1、PSR-2、PSR-12以及Symfony等）的代码，并自动修复其中的大部分问题。
- 高度可配置的规则集： 允许用户创建自定义的规则集，以适应团队特定的编码风格或项目要求。这使得它非常灵活，可以适应各种复杂的场景。
- 本地修复能力： 开发者可以在本地开发环境中运行PHP-CS-Fixer，实时修复代码格式问题，避免将不符合规范的代码提交到版本控制系统。
- 无缝集成CI/CD： 可以轻松集成到各种CI/CD管道中，作为代码质量门禁的一部分。在Pull Request提交时，CI系统可以自动运行PHP-CS-Fixer来检查代码格式，并在发现问题时阻止合并，或提供修复建议。
- 活跃的社区支持： 作为一个成熟的开源项目，PHP-CS-Fixer拥有活跃的社区支持和持续的更新，确保其稳定性和功能完善性。
4. PHP-CS-Fixer的安装与基本使用
4.1 安装
PHP-CS-Fixer通常通过Composer进行安装，建议将其作为项目的开发依赖安装：
composer require --dev friendsofphp/php-cs-fixer
安装完成后，可执行文件通常位于 vendor/bin/php-cs-fixer。
4.2 基本使用
检查代码格式（不修复）：
vendor/bin/php-cs-fixer fix --dry-run --diff src/
上述命令会检查 src/ 目录下的PHP文件，并显示需要修复的差异，但不会实际修改文件。--dry-run 表示模拟运行，--diff 会显示具体的差异。
自动修复代码格式：
vendor/bin/php-cs-fixer fix src/
此命令会遍历 src/ 目录下的PHP文件，并自动修复所有发现的格式问题。
5. 配置自定义规则集
为了适应团队的编码规范，PHP-CS-Fixer允许通过配置文件来定义规则集。通常，这个配置文件命名为 .php-cs-fixer.dist.php 或 .php-cs-fixer.php，放置在项目的根目录。
以下是一个示例配置文件，它使用了PSR-12标准，并额外添加了一些自定义规则：
in(__DIR__) // 扫描当前目录及其子目录
->exclude('vendor') // 排除 vendor 目录
->exclude('node_modules') // 排除 node_modules 目录
->notPath('bootstrap/cache') // 排除特定文件或目录
->notPath('storage/logs')
->name('*.php') // 只处理 .php 文件
->ignoreDotFiles(true) // 忽略以点开头的文件（如.env）
->ignoreVCS(true); // 忽略版本控制系统文件（如.git）
return (new PhpCsFixer\Config())
->setRules([
'@PSR12' => true, // 使用PSR-12标准
'array_syntax' => ['syntax' => 'short'], // 数组使用短语法
'cast_spaces' => ['space' => 'none'], // 类型转换后不留空格
'concat_space' => ['spacing' => 'none'], // 连接符前后不留空格
'ordered_imports' => ['sort_algorithm' => 'alpha'], // 导入语句按字母顺序排序
'single_line_comment_style' => ['comment_types' => ['hash']], // 单行注释使用双斜杠而不是井号
'no_unused_imports' => true, // 移除未使用的导入
'blank_line_after_namespace' => true, // 命名空间声明后有空行
'blank_line_after_opening_tag' => false, // PHP文件开头标签后没有空行
'declare_strict_types' => true, // 强制声明严格类型
'phpdoc_indent' => true, // PHPDoc注释缩进
'phpdoc_order' => true, // PHPDoc标签顺序
'phpdoc_scalar' => true, // PHPDoc标量类型
'phpdoc_single_line_var_spacing' => true, // 单行变量PHPDoc间距
'phpdoc_trim' => true, // PHPDoc修剪
'phpdoc_types' => true, // PHPDoc类型
'phpdoc_var_without_name' => true, // PHPDoc变量无名称
'trailing_comma_in_multiline' => ['elements' => ['arrays', 'arguments', 'parameters']], // 多行数组、参数等末尾使用逗号
])
->setFinder($finder)
->setCacheFile(__DIR__ . '/.php-cs-fixer.cache'); // 设置缓存文件，提高性能配置完成后，运行 vendor/bin/php-cs-fixer fix 命令时，它会自动加载并应用该配置文件中的规则。
6. 在持续集成(CI)中的应用
将PHP-CS-Fixer集成到CI流程中，可以自动化代码格式检查，确保所有提交的代码都符合团队规范。以下是在CI中应用PHP-CS-Fixer的常见模式：
-
在Pull Request检查中运行： 当开发者提交Pull Request时，CI系统会自动触发构建。其中一个步骤就是运行PHP-CS-Fixer的 fix --dry-run --diff 命令。
- 如果命令成功（即没有格式问题），CI检查通过。
- 如果命令失败（即发现格式问题），CI检查失败，阻止Pull Request合并，并提供详细的错误报告，提示开发者修复。
-
示例GitHub Actions配置片段：
name: Code Style Check on: [pull_request] jobs: php-cs-fixer: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v3 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.2' extensions: mbstring, pdo_mysql # 根据项目需要添加扩展 tools: composer - name: Install dependencies run: composer install --no-interaction --prefer-dist --optimize-autoloader - name: Run PHP-CS-Fixer run: vendor/bin/php-cs-fixer fix --dry-run --diff --verbose # 如果希望在CI中自动修复并提交，需要额外的配置和权限 # 例如： # - name: Run PHP-CS-Fixer and commit changes # run: | # vendor/bin/php-cs-fixer fix # git config user.name github-actions # git config user.email github-actions@github.com # git add . # git commit -m "Fix code style" || echo "No changes to commit" # git push上述配置片段展示了如何在GitHub Actions中运行PHP-CS-Fixer。它会在每次Pull Request时检查代码风格，并输出详细的差异报告。
7. 总结与最佳实践
PHP-CS-Fixer是PHP项目实现代码格式化和风格统一的强大工具。通过合理配置和集成到CI流程中，可以显著提升代码质量、减少代码审查负担，并确保团队协作的顺畅。
最佳实践建议：
- 尽早引入： 在项目初期就引入PHP-CS-Fixer，并定义好团队的编码规范，避免后期大规模的代码风格重构。
- 配置 .php-cs-fixer.dist.php： 使用项目级别的配置文件来管理规则，并将其纳入版本控制。
- 集成到IDE： 许多现代IDE（如PhpStorm、VS Code）都提供了PHP-CS-Fixer的插件或集成，允许开发者在保存文件时自动修复格式问题。
- 教育团队成员： 确保所有团队成员都了解并遵循代码格式规范，并在本地开发时使用PHP-CS-Fixer。
- CI作为守门员： 将PHP-CS-Fixer作为CI流程中的强制检查项，确保只有符合规范的代码才能被合并到主分支。
通过以上方法，PHP-CS-Fixer能够有效地替代clang-format在C/C++/Objective-C领域所扮演的角色，为PHP和包含PHP的HTML代码提供一致、专业的自动化格式化解决方案。
