# code-review

**Repository Path**: yinliequan/code-review

## Basic Information

- **Project Name**: code-review
- **Description**: 质量检查
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-14
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本地代码审查工具

一个自定义的本地项目代码自查工具，用于代码质量检查和规范约束。

## 📖 目录

- [项目简介](#项目简介)
- [特性](#特性)
- [环境要求](#环境要求)
- [安装](#安装)
- [快速开始](#快速开始)
- [工具配置及说明](#工具配置及说明)
- [集成到 GrumPHP](#集成到-grumphp)
- [运行检查](#运行检查)
- [常见问题](#常见问题)

## 项目简介

本项目集成了一些常用的代码质量检查工具，并对工具 PHP_CodeSniffer 自定义了一些检查，帮助团队保持代码质量和一致性。

## ✨ 特性

### 集成工具

| 工具名称 | 主要功能 | 特点 |
|---------|---------|------|
| **PHP-CS-Fixer** | 自动修复代码风格 | 自动化修复、可配置规则、PSR 规范 |
| **PHP_CodeSniffer** | 编码规范检查 | 可扩展、自定义规则、PSR 标准 |
| **parallel-lint** | 并行语法检查 | 快速检测语法错误（如缺少分号、括号不匹配等） |
| **PHPStan** | 静态代码分析 | 检测类型错误、未定义变量、死代码等潜在问题 |
| **Psalm** | 静态类型检查 | 深度类型推断、空指针引用检测 |
| **Phan** | 深度静态分析 | 函数调用分析、继承检查、参数匹配验证 |
| **GrumPHP** | Git 钩子自动化 | 统一调度所有工具、自动化流程管控 |

## 💻 环境要求

- PHP >= 7.4
- Composer

## 📦 安装

```bash
composer require jaye/code-review
```

## 🚀 快速开始

### 1. 安装后自动生成配置文件

安装完成后，项目根目录会自动生成以下配置文件：

```bash
# 配置文件列表
php-cs-fixer.dist.php    # PHP-CS-Fixer 配置
phpstan.neon              # PHPStan 配置
psalm.xml                 # Psalm 配置
phan.php                  # Phan 配置
phpcs-ruleset.xml         # PHP_CodeSniffer 规则集
grumphp.yml               # GrumPHP 钩子配置
```

> 💡 **提示**：记得将这些配置文件添加到 `.gitignore` 中

### 2. 配置文件 .gitignore

```gitignore
# 代码审查工具配置
php-cs-fixer.dist.php
phpstan.neon
phpstan-baseline.php
psalm.xml
psalm-baseline.xml
phan.php
.phan.baseline.php
phpcs-ruleset.xml
grumphp.yml
.php_cs.cache
```

## ⚙️ 工具配置及说明

### PHP-CS-Fixer 配置

在 `php-cs-fixer.dist.php` 中修改检查目录和排除目录：

```php
$finder = Finder::create()
    ->in([
        __DIR__.'/src/',
    ])  // 指定检查目录
    ->exclude([
        __DIR__.'/vendor',
        __DIR__.'/test',
    ])  // 排除指定目录
    ->name('*.php')
    ->ignoreDotFiles(true)   // 忽略以点号开头的文件
    ->ignoreVCS(true);       // 忽略版本控制文件
```

### PHPStan 配置

在老项目中使用质量检查，可以使用**基线文件**来屏蔽旧文件中已存在的大量报错，只关注新代码或指定文件的质量问题。

**生成基线文件：**
```bash
./vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.php
```

**启用基线文件**（在 `phpstan.neon` 中配置）：
```neon
includes:
    - phpstan-baseline.php
```

### Psalm 配置

Psalm 也可以使用基线文件忽略旧文件错误。

**生成基线文件：**
```bash
./vendor/bin/psalm --update-baseline
```
生成的基线文件为 `psalm-baseline.xml`

### Phan 配置

**核心配置项：**

| 配置项 | 说明 |
|--------|------|
| `exclude_file_list` | 排除特定文件 |
| `exclude_analysis_directory_list` | 排除分析目录（如 vendor） |
| `directory_list` | 待分析目录 |
| `file_list` | 项目中的核心入口文件、公共工具文件等，可通过 file_list 显式声明，确保每次分析都不会遗漏这些关键文件 |

**生成基线文件：**
```bash
./vendor/bin/phan --save-baseline
```

**建议配置：**
```php
'consistent_hashing_file_order' => false,
'simplify_ast' => false,
'baseline_path' => '.phan.baseline.php'
```

### PHP_CodeSniffer 配置

配置文件：`phpcs-ruleset.xml`

### GrumPHP 配置

配置文件：`grumphp.yml`

## 🔌 集成到 GrumPHP

在 `grumphp.yml` 中配置所有检查任务，实现提交前自动化检查。

### 核心配置说明

```yaml
grumphp:
    stop_on_failure: true           # 某个检查失败时立即停止
    ignore_unstaged_changes: false  # 检查时包含未暂存的代码
    hide_circumvention_tip: true    # 隐藏跳过检查的提示
    process_timeout: 300            # 单个任务超时时间（秒）
    parallel:
        enabled: true               # 开启并行执行
        max_workers: 32             # 最大并行进程数
    fixer:
        enabled: true               # 开启自动修复
        fix_by_default: true       # 默认自动修复代码风格
```

### 任务配置说明

#### 语法检查 - phplint
- 最基础、最快的检查，优先执行
- 检测缺少分号、括号不匹配等语法错误

#### 代码风格修复 - phpcsfixer
- 基于配置文件自动修复代码风格
- 支持缓存机制，提升重复检查速度
- 显示修复前后的代码差异

#### 静态类型检查 - phpstan
- 检测类型错误、未定义方法、参数不匹配等
- 支持级别配置（0-9），建议从低级别开始逐步提升
- 使用基线文件可忽略旧代码错误

#### 静态类型检查 - psalm
- 比 PHPStan 更侧重类型推断、注释检查
- 支持多线程执行（可根据 CPU 调整）
- 同样支持基线文件机制

#### 深度静态分析 - phan
- 轻量级深度静态分析
- 支持多种输出格式（text/json/xml）
- 检测函数调用、继承关系等深层问题

#### 代码规范检查 - phpcs
- 补充 phpcsfixer，侧重规则校验
- 遵循 PSR12 标准
- 可配置错误级别和报告格式

### 测试套件配置

| 套件名称 | 包含任务 | 触发时机 |
|---------|---------|---------|
| `dev` | phplint, phpstan | 手动执行 |
| `git_commit_msg` | phpcs, phplint, phpstan, psalm | Git 提交信息检查 |
| `git_pre_commit` | phpcs, phplint, phpstan, psalm, phpcsfixer | Git 预提交钩子（核心）**

## ▶️ 运行检查

### 单独运行各工具

| 检查类型 | 命令 | 说明 |
|---------|------|------|
| **语法检查** | `vendor/bin/parallel-lint src/` | 快速检测语法错误 |
| **代码风格修复** | `vendor/bin/php-cs-fixer fix src/` | 自动修复代码风格 |
| **代码风格检查** | `vendor/bin/php-cs-fixer fix --dry-run src/` | 只检查不修复 |
| **PHPStan 分析** | `vendor/bin/phpstan analyse --level=7 src/` | 静态类型检查 |
| **Psalm 分析** | `vendor/bin/psalm --show-info=false` | 静态类型检查 |
| **Phan 分析** | `vendor/bin/phan -k phan.php` | 深度静态分析 |
| **代码规范检查** | `vendor/bin/phpcs --standard=./phpcs-ruleset.xml src/` | 编码规范检查 |
| **代码规范修复** | `vendor/bin/phpcbf --standard=./phpcs-ruleset.xml src/` | 自动修复规范问题 |

### GrumPHP 钩子检查

| 命令 | 说明 |
|------|------|
| `vendor/bin/grumphp run` | 运行默认测试套件 |
| `vendor/bin/grumphp run --testsuite=dev` | 运行开发测试套件 |
| `vendor/bin/grumphp run --testsuite=git_pre_commit` | 运行预提交钩子检查 |

### 生成基线文件

| 工具 | 命令 |
|------|------|
| PHPStan | `./vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.php` |
| Psalm | `./vendor/bin/psalm --update-baseline` |
| Phan | `./vendor/bin/phan --save-baseline` |

## ❓ 常见问题

### Q1: 如何禁用某个检查工具？

在 `grumphp.yml` 的对应任务中添加 `enabled: false`，或直接从 testsuites 中移除该任务。

### Q2: 如何加快检查速度？

- 启用缓存机制（各工具默认已开启）
- 使用基线文件屏蔽旧代码错误
- 调整 `parallel.max_workers` 参数增加并行进程数
- 只检查变更的文件（Git 钩子模式下自动实现）

### Q3: 如何跳过 Git 钩子检查？

```bash
git commit --no-verify -m "跳过检查的提交信息"
```

> ⚠️ **注意**：不建议频繁跳过检查，这会降低代码质量。

### Q4: 基线文件多久需要更新一次？

建议在以下情况更新基线文件：
- 重构大量代码后
- 升级工具版本后
- 基线文件中的错误已修复

### Q5: 如何选择合适的 PHPStan 分析级别？

| 级别 | 适用场景 | 检查严格度 |
|------|---------|-----------|
| 0-1 | 初期接入老项目 | 最宽松 |
| 2-4 | 正常开发 | 中等（推荐从 4 开始） |
| 5-7 | 高质量项目 | 较严格 |
| 8-9 | 新项目 / 极致要求 | 最严格 |

建议从低级别开始，逐步提升到更高级别。

## 📝 License

MIT