detain/php-duplication-samples
GitHub: detain/php-duplication-samples
一个包含 54 种 PHP 重复代码模式的综合参考语料库，用于教育、重构参考以及对比测试各类代码重复检测工具的准确性。
Stars: 0 | Forks: 0
# PHP 重复代码示例
一个用于 PHP 代码重复模式的综合参考语料库和基准测试套件。本项目提供了横跨 54 个不同类别的结构化重复代码示例集合，并附带重构解决方案以及用于比较重复检测工具的工具集。
## 目录
- [概述](#overview)
- [功能](#features)
- [目录结构](#directory-structure)
- [重复类别](#duplication-categories)
- [基准测试工具](#benchmark-tools)
- [快速开始](#getting-started)
- [添加新示例](#adding-new-samples)
- [贡献](#contributing)
- [许可证](#license)
- [参考](#references)
## 概述
代码重复是软件项目中最常见的技术债务来源之一。本项目可用作：
1. **教育资源** - 了解代码重复可以采取的多种形式
2. **基准语料库** - 测试和比较重复检测工具
3. **重构参考** - 查看如何对重复代码进行去重
该语料库包含 **54 个不同类别** 的重复模式，从明显的复制粘贴克隆到需要深入分析才能检测出的细微语义重复。
## 功能
- **54 种重复类别** - 全面涵盖从完全克隆到语义等价的各种重复类型
- **重构解决方案** - 每个类别都包含展示如何消除重复的去重实现
- **基准测试套件** - 用于重复检测工具的端到端比较框架
- **多种检测工具** - 支持 phpcpd, jscpd, PMD-CPD, Simian 和 phpdup
- **真实评分标准** - 具有已知重复拓扑结构的综合语料库，用于精确测量
- **支持 PHP 8.1+** - 全面采用现代 PHP 模式和严格类型
## 目录结构
```
php-duplication-samples/
├── samples/ # 54 categories of duplicated code examples
│ ├── algorithm/ # Algorithm duplication (20 samples)
│ ├── architectural/ # Architectural patterns (10 samples)
│ ├── behavioral/ # Behavioral duplication (20 samples)
│ ├── build/ # Build/deployment duplication (9 samples)
│ ├── caching/ # Caching patterns (10 samples)
│ ├── clone_type_1/ # Type-1 clones (exact copies) (20 samples)
│ ├── clone_type_2/ # Type-2 clones (renamed) (10 samples)
│ ├── clone_type_3/ # Type-3 clones (modified) (15 samples)
│ ├── clone_type_4/ # Type-4 clones (semantic) (10 samples)
│ ├── configuration/ # Configuration duplication (20 samples)
│ ├── copy_paste/ # Direct copy-paste examples (60 samples)
│ ├── cross_service/ # Cross-service duplication (10 samples)
│ ├── data/ # Data/constant duplication (20 samples)
│ ├── dependency/ # Dependency injection duplication (10 samples)
│ ├── documentation/ # Documentation duplication (10 samples)
│ ├── error_handling/ # Error handling patterns (various)
│ ├── event/ # Event handling duplication (10 samples)
│ ├── functional/ # Functional duplication (10 samples)
│ ├── knowledge/ # Business knowledge duplication (20 samples)
│ ├── lexical/ # Lexical patterns (10 samples)
│ ├── localization/ # i18n duplication (10 samples)
│ ├── logic/ # Business logic duplication (10 samples)
│ ├── mapping/ # Data mapping duplication (10 samples)
│ ├── monitoring/ # Monitoring instrumentation (10 samples)
│ ├── orm_query_duplication/ # ORM query patterns (10 samples)
│ ├── permission/ # Authorization patterns (10 samples)
│ ├── process/ # Process/workflow duplication (10 samples)
│ ├── protocol/ # Protocol handling (50 samples)
│ ├── query/ # Database query duplication (30 samples)
│ ├── representation/ # Model duplication (20 samples)
│ ├── schema/ # Schema duplication (10 samples)
│ ├── semantic/ # Semantic duplication (20 samples)
│ ├── serialization/ # Serialization patterns (10 samples)
│ ├── structural/ # Structural duplication (20 samples)
│ ├── syntactic/ # Syntactic patterns (10 samples)
│ ├── temporal/ # Temporal patterns (20 samples)
│ ├── test/ # Test duplication (20 samples)
│ ├── textual/ # Textual duplication (10 samples)
│ ├── type/ # Type-specific duplication (20 samples)
│ ├── ui/ # UI duplication (20 samples)
│ ├── validation_*/ # Validation patterns (email, password, phone)
│ ├── workflow/ # Workflow patterns (10 samples)
│ └── ... # Additional categories
│
├── refactored/ # Deduplicated refactorings
│ ├── algorithm/ # Refactored algorithm solutions
│ ├── behavioral/ # Refactored behavioral patterns
│ ├── permission/ # Refactored authorization
│ └── ... # One refactored solution per sample
│
├── bench/ # Benchmark harness
│ ├── run.php # Execute all tools on all corpora
│ ├── run-samples.php # Run detection on sample categories
│ ├── score.php # Compute precision/recall/F1
│ ├── corpora.php # Download/manage test corpora
│ ├── comparative.php # Quick one-shot comparison
│ ├── run-all.sh # Full benchmark automation
│ ├── feature-matrix.md # Tool capability comparison
│ ├── tools/ # Auto-downloaded tools
│ └── results/ # Benchmark results
│
├── samples.json # Master index of all categories and samples
├── code_duplication_types.md # Type taxonomy with examples
├── code_duplication_challenges.md # "Hidden" duplication patterns
└── code_duplication_alternatives.md # Alternative tools reference
```
### 示例文件结构
每个示例目录都遵循以下模式：
```
samples///
├── block_a.php # First duplicated code block
├── block_b.php # Second duplicated code block
├── block_c.php # Third duplicated code block (optional)
└── refactored/
└── code.php # Deduplicated refactored solution
```
## 重复类别
该项目定义了 **54 个不同类别** 的代码重复。以下是摘要：
### 克隆分类（Roy & Ossher 分类法）
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **clone_type_1** | 除了空格/注释外完全相同 | 20 |
| **clone_type_2** | 重命名了标识符/字面量 | 10 |
| **clone_type_3** | 添加/删除/修改了语句 | 15 |
| **clone_type_4** | 仅语义等价 | 10 |
### 语义与业务重复
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **semantic** | 相同的业务规则，不同的代码 | 20 |
| **knowledge** | 业务事实存在于多个地方 | 20 |
| **behavioral** | 相同的行为，不同的实现 | 20 |
| **domain_rule** | 核心不变量重复 | 不定 |
| **policy** | 业务策略分散 | 不定 |
### 结构性重复
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **architectural** | 相同的架构，不同的模块 | 10 |
| **structural** | 相同的 pipeline/workflow 模式 | 20 |
| **syntactic** | 相同的 AST 结构，不同的内容 | 10 |
| **template** | 相同的模板，不同的参数 | 不定 |
### 代码模式重复
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **algorithm** | 相同的算法模式，不同的阈值 | 20 |
| **logic** | 重复的条件业务规则 | 10 |
| **validation** | 重复的输入验证 | 各种 |
| **error_handling** | 异常处理模式 | 各种 |
| **caching** | 重复的缓存管理 | 10 |
| **monitoring** | 重复的插桩 | 10 |
### 数据与配置重复
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **data** | 重复的常量/字面量 | 20 |
| **configuration** | 重复的 Config 模式 | 20 |
| **schema** | 重复的 schema 定义 | 10 |
| **representation** | 同一实体的多个模型 | 20 |
### 横切关注点
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **permission** | 重复的授权检查 | 10 |
| **dependency** | 重复的依赖注入 | 10 |
| **documentation** | 文档分散且不一致 | 10 |
| **localization** | 重复的 i18n 模式 | 10 |
| **serialization** | 重复的序列化逻辑 | 10 |
### ORM 与数据库模式
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **query** | 重复的 SQL/ORM 查询 | 30 |
| **orm_query_duplication** | 相同操作，不同 ORM API | 10 |
| **nosql_document_duplication** | 相同操作，不同 NoSQL API | 10 |
| **graph_query_duplication** | 相同操作，不同图数据库 API | 5 |
| **timeseries_cache_duplication** | 相同操作，不同缓存 API | 5 |
### 其他模式
| 类别 | 描述 | 示例 |
|----------|-------------|---------|
| **copy_paste** | 直接的复制粘贴示例 | 60 |
| **textual** | 相同的文本字符串 | 10 |
| **lexical** | Token 级别的相似性 | 10 |
| **functional** | 相同的功能结果，不同的代码 | 10 |
| **process** | 被代码化的手动流程 | 10 |
| **cross_service** | 跨微服务的重复 | 10 |
| **build** | CI/CD 配置重复 | 9 |
| **workflow** | 重复的 workflow 模式 | 10 |
| **ui** | 重复的界面模式 | 20 |
| **event** | 重复的事件处理 | 10 |
| **protocol** | 重复的协议处理 | 50 |
| **test** | 重复的测试设置/夹具 | 20 |
## 基准测试工具
基准测试套件支持以下重复检测工具：
| 工具 | 类型 | 描述 |
|------|------|-------------|
| **phpdup** | 主要 | 自定义 PHP 重复检测器（内置于本仓库） |
| **phpcpd** | 外部 | Sebastian Bergmann 的 PHP 复制/粘贴检测器 |
| **jscpd** | 外部 | 通过 JavaScript 实现的多语言 CPD 克隆检测 |
| **pmd-cpd** | 外部 | 用于 PHP 的 PMD CPD（通过 PHPMD） |
| **simian** | 外部 | 商业重复检测器（基于 Java） |
### 工具对比矩阵
| 功能 | phpdup | phpcpd | jscpd | pmd-cpd | simian |
|---------|--------|--------|-------|---------|--------|
| 基于 Token 的检测 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 基于 AST 的检测 | ✓ | - | - | - | ✓ |
| 最小 token 阈值 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 忽略注解 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 语言支持 | PHP | PHP | 223+ | Java, PHP 等 | Java, C# 等 |
| JSON 输出 | ✓ | XML | JSON | XML | 文本 |
| 免费/开源 | ✓ | ✓ | ✓ | ✓ | - |
## 快速开始
### 环境要求
- **PHP 8.1+**，包含 CLI 和所需扩展
- **Composer**（用于某些基准测试依赖）
- **Node.js 18+**（可选，用于 jscpd）
- **Git**（用于下载语料库）
### 运行基准测试
#### 完整基准测试套件
```
# 运行完整 benchmark（下载工具、克隆语料库、运行所有测试）
./bench/run-all.sh
```
这将生成：
- `bench/results/latest.md` - 每个（工具，语料库）的实际时间、RSS 及集群数量
- `bench/results/detection-rate.md` - 在合成语料库上的精确率/召回率/F1 分数
#### 单个组件
```
# 下载/刷新测试语料库
php bench/corpora.php
# 在所有工具上仅运行一个语料库
php bench/run.php --corpus=synthetic-fuzz --label=initial
# 对特定 run 进行评分
php bench/score.php bench/results/initial.json
# 快速比较检查
php bench/comparative.php
```
#### 在示例类别上运行
```
# 在所有样本上运行检测
php bench/run-samples.php
# 在特定类别上运行
php bench/run-samples.php --category=permission --id=1
```
### 添加新示例
#### 示例结构
每个示例都需要：
1. **重复的代码块**（`block_a.php`, `block_b.php`, `block_c.php`）
2. **重构解决方案**（`refactored/code.php`）
3. **在 `samples.json` 中添加条目**
#### 示例
```
// samples/my_category/1/block_a.php
标签：Cutter, ffuf, MITM代理, OpenVAS, PHP, 代码重构, 测试数据集, 重复代码检测