PHP项目代码提交规范如何制定执行

wen PHP项目 2026-07-01 24

本文目录导读：

PHP项目代码提交规范如何制定执行

提交规范的核心内容
如何落地执行（工具 + 流程）
制定团队约定文档
常见问题与解决策略
推荐的最小可行方案

制定并执行一套有效的 PHP 项目代码提交规范，不仅能提升代码质量，还能让团队协作更顺畅、代码审查更高效，以下是一套从制定到执行的完整方案，重点围绕 Git 提交信息规范 和 代码风格规范 展开。

提交规范的核心内容

Git 提交信息规范（Angular 规范）

这是最广泛使用的规范，结构清晰,易于自动化。

格式：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

type（必选）：提交的类别，常见：
- feat — 新功能
- fix — 修复 bug
- docs — 文档变更
- style — 代码格式变动（不影响功能，如空格、格式化）
- refactor — 重构（既不修复 bug 也不增加功能）
- perf — 性能优化
- test — 添加或修改测试
- chore — 构建过程或辅助工具的变动
- ci — CI 配置变更
scope（可选）：影响范围，如模块名、组件名（user, payment）
subject（必选）：简短描述，50 字以内，首字母小写，不加句号
body（可选）：详细说明，可以写为什么这么做、怎么做的
footer（可选）：关联 Issue、Breaking Change 说明

示例：

feat(auth): add OAuth2 login support
Implement OAuth2 login using Laravel Socialite.
Users can now log in via Google or GitHub.
Closes #123
BREAKING CHANGE: The old login endpoint is deprecated.

代码风格规范

PHP 项目通常采用 PSR-12（扩展自 PSR-2）作为编码风格标准。

缩进：4 个空格（不是 Tab）
命名：
- 类名：PascalCase（UserController）
- 方法名、变量名：camelCase（getUserName）
- 常量：大写字母+下划线（MAX_RETRY_COUNT）
花括号：类和函数另起一行，控制结构在同一行（PSR-12 明确）
类型声明：对参数和返回值尽量使用强类型
DocBlock：公共方法、复杂逻辑、关键组件需要

示例：

<?php
declare(strict_types=1);
namespace App\Services;
class UserService
{
    public function getFullName(string $firstName, string $lastName): string
    {
        return trim($firstName . ' ' . $lastName);
    }
}

如何落地执行（工具 + 流程）

使用工具强制检查

a) 代码风格 => PHP CS Fixer

安装（Composer 全局或 dev 依赖）：

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

创建 .php-cs-fixer.dist.php 配置文件：

<?php
$finder = PhpCsFixer\Finder::create()
    ->in(__DIR__)
    ->exclude('vendor')
    ->name('*.php');
return (new PhpCsFixer\Config())
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
        'no_unused_imports' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
    ])
    ->setFinder($finder);

然后在 CI 或 commit 前运行：

php-cs-fixer fix

b) 提交信息规范 => commitlint + husky（Node 环境）

如果你的项目是 PHP + JS 前后端分离，或团队接受 Node 依赖：

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

commitlint.config.js：

module.exports = { extends: ['@commitlint/config-conventional'] };

如果不想引入 Node，可以用 PHP 实现的 小脚本 或 Git Hooks 自行校验。

c) PHP 静态分析 => PHPStan 或 Psalm

确保代码质量和类型安全：

composer require --dev phpstan/phpstan

配置 phpstan.neon,然后运行：

phpstan analyse

使用 Git Hooks 自动化

推荐使用 husky（Node）或 pre-commit（Python/PHP）或纯 shell 脚本。

纯 Shell 版 `.git/hooks/pre-commit`

#!/bin/sh
# 检查 PHP 语法
php -l "$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')" > /dev/null 2>&1
# 运行 php-cs-fixer（只修改暂存区文件）
git diff --cached --name-only --diff-filter=ACM -- '*.php' | xargs -r vendor/bin/php-cs-fixer fix --diff --using-cache=no
# 重新暂存修复后的文件
git diff --name-only --cached -- '*.php' | xargs -r git add
# 运行 PHPStan（可选）
vendor/bin/phpstan analyse

然后赋予执行权限：

chmod +x .git/hooks/pre-commit

推荐： 使用 husky 管理，因为更跨平台、易维护。

在 CI/CD 中强制执行

以 GitHub Actions 为例，在 .github/workflows/ci.yml 中加入：

name: CI
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          tools: composer:v2
      - run: composer install
      - name: PHP CS Fixer
        run: vendor/bin/php-cs-fixer fix --dry-run --diff
      - name: PHPStan
        run: vendor/bin/phpstan analyse
      - name: Commitlint
        # 需要 Node 运行 commitlint
        run: |
          npm install @commitlint/cli @commitlint/config-conventional
          echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js
          npx commitlint --from ${{ github.event.before }} --to ${{ github.event.after }} --verbose

制定团队约定文档

创建一个 CONTRIBUTING.md 放在项目根目录,包含：

提交信息格式说明
代码风格要求（直接引用 PSR-12 及额外规则）
测试要求（如必须包含单元测试）
分支命名规范（可选，如 feature/xxx, fix/xxx, hotfix/xxx）
合并请求（PR）模板

示例 PR 模板（.github/pull_request_template.md）：

## 描述
简要描述本次 PR 做了什么。
## 类型
- [ ] feat
- [ ] fix
- [ ] refactor
- [ ] docs
- [ ] style
- [ ] test
## 是否破坏兼容性
- [ ] 是
- [ ] 否
## 关联 Issue
Fixes #(issue)

常见问题与解决策略

问题	解决方案
团队成员不熟悉规范	新人培训 + 合并请求中要求规范检查
不喜欢手动写 commit message	使用 `commitizen`（交互式生成）
PHP CS Fixer 自动修改代码	在 commit 前自动执行 `fix`，再重新 `git add`
部分文件不需要检查（如第三方包）	在 `.php-cs-fixer.dist.php` 中用 `exclude` 忽略
历史提交不规范	只要求从今天开始的新提交规范，旧的不再追溯