PHP/HTML代码格式化：替代Clang-Format的专业方案

本文旨在解决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文件，并自动修复所有发现的格式问题。

代码小浣熊

代码小浣熊是基于商汤大语言模型的软件智能研发助手，覆盖软件需求分析、架构设计、代码编写、软件测试等环节

51

查看详情

5. 配置自定义规则集

为了适应团队的编码规范，PHP-CS-Fixer允许通过配置文件来定义规则集。通常，这个配置文件命名为 .php-cs-fixer.dist.php 或 .php-cs-fixer.php，放置在项目的根目录。

以下是一个示例配置文件，它使用了PSR-12标准，并额外添加了一些自定义规则：

<?php

$finder = (new PhpCsFixer\Finder())
    ->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的常见模式：

1. 在Pull Request检查中运行： 当开发者提交Pull Request时，CI系统会自动触发构建。其中一个步骤就是运行PHP-CS-Fixer的 fix --dry-run --diff 命令。

   • 如果命令成功（即没有格式问题），CI检查通过。
   • 如果命令失败（即发现格式问题），CI检查失败，阻止Pull Request合并，并提供详细的错误报告，提示开发者修复。

2. 示例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代码提供一致、专业的自动化格式化解决方案。

以上就是PHP/HTML代码格式化：替代Clang-Format的专业方案的详细内容，更多请关注php中文网其它相关文章！