PHP/HTML代码格式化利器：PHP-CS-Fixer实践指南

本文针对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免费学习笔记（深入）”；

安装步骤：

1. 全局安装（不推荐，但可行）：

   composer global require friendsofphp/php-cs-fixer

   登录后复制

   然后确保Composer的bin目录在您的PATH中。

2. 项目局部安装（推荐）：

   composer require --dev friendsofphp/php-cs-fixer

   登录后复制

   这会将PHP-CS-Fixer安装到项目的vendor/bin目录下。

基本使用命令：

安装完成后，您可以通过以下命令运行PHP-CS-Fixer：

• 检查文件（不修改）：

  

  比格设计

  比格设计是135编辑器旗下一款一站式、多场景、智能化的在线图片编辑器

  124

  查看详情

  ./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 = PhpCsFixer\Finder::create()
    ->in(__DIR__) // 扫描当前目录及其子目录
    ->exclude('vendor') // 排除vendor目录
    ->name('*.php') // 只处理.php文件
    ->ignoreDotFiles(true) // 忽略点文件
    ->ignoreVCS(true) // 忽略版本控制文件
;

return (new PhpCsFixer\Config())
    ->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) // 允许可能改变代码行为的“危险”规则
;

在这个配置文件中：

• PhpCsFixer\Finder 用于定义哪些文件和目录应该被扫描。
• 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配置中：

1. 当有拉取请求或推送到main/master分支时，工作流将被触发。
2. 它会检出代码，设置PHP环境并安装Composer依赖。
3. 最后，运行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流程的集成，团队可以有效地在开发早期捕获并修复代码风格问题，从而提升整体代码质量和开发效率。

以上就是PHP/HTML代码格式化利器：PHP-CS-Fixer实践指南的详细内容，更多请关注php中文网其它相关文章！