# php-trie-filter

**Repository Path**: meystack/php-trie-filter

## Basic Information

- **Project Name**: php-trie-filter
- **Description**: PHP8.1 敏感词过滤C语言扩展
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# trie_filter — PHP 8.1+ 敏感词过滤扩展

在对一个PHP项目进行敏感词过滤的时候，除了API我们使用DFA以外，在长文本的异步审核工作中，，哪怕PHP是常驻内存类型的也无法使用AC自动机，10万+敏感词直接撑爆内存，在写了新算法搞成二进制的AC自动机后，单次审核在50ms左右，无法用于生产环境，然后就发现了php_trie_filter项目，基于 Double-Array Trie 树的 PHP C 扩展，使用 cmake 构建，但是太老了，并且不兼容PHP8.1，fork了代码升级后并修复了一些问题，经过测试10w+敏感词查询均在0.010ms以下，特别适用PHP开发者！本仓库非原创作者，原作者已经找不到了，我只是升级支持PHP8.1而已，站在巨人的肩膀上，让我们看的更远！


## 依赖

| 依赖 | 最低版本 | CentOS 安装 |
|------|---------|------|
| PHP | 8.1+ | `yum install php-devel` |
| libdatrie | 0.2.4+ | `yum install libdatrie-devel` |
| cmake | 3.10+ | `yum install cmake` |
| gcc/clang | C99+ | `yum install gcc gcc-c++ make` |

## 编译安装

```bash
# 1. 安装依赖（CentOS/RHEL）
yum install libdatrie-devel php-devel cmake gcc gcc-c++ make

# 2. 构建
mkdir -p build && cd build
cmake ..
make -j$(nproc)

# 3. 安装扩展
sudo make install

# 4. 启用扩展（二选一）
# 方式A: 写入 ini 文件（路径以实际 php.ini 为准）
echo "extension=trie_filter.so" >> $(php -i | grep 'Loaded Configuration File' | awk '{print $NF}')
sudo systemctl restart php-fpm

# 方式B: 命令行加载
php -d extension=trie_filter.so test.php
```

### 验证安装

```bash
php -m | grep trie_filter
# trie_filter
```

## 使用示例

### 构建词库文件

```php
<?php
// 1. 创建空的 Trie 树
$trie = trie_filter_new();

// 2. 逐个添加敏感词
$words = ['赌博', '色情', '暴力', '恐怖袭击', '枪支'];
foreach ($words as $word) {
    trie_filter_store($trie, $word);
}

// 3. 保存到文件（只需做一次，后续直接加载）
trie_filter_save($trie, __DIR__ . '/sensitive.tree');
trie_filter_free($trie);
```

### 搜索敏感词

```php
<?php
// 加载词库
$trie = trie_filter_load(__DIR__ . '/sensitive.tree');

// 搜索所有匹配
$text = '这段文本包含赌博和色情内容';
$results = trie_filter_search_all($trie, $text);

foreach ($results as $match) {
    $word = substr($text, $match[0], $match[1]);
    echo "命中: {$word} (位置: {$match[0]}, 长度: {$match[1]})" . PHP_EOL;
}
// 输出:
// 命中: 赌博 (位置: 8, 长度: 6)
// 命中: 色情 (位置: 17, 长度: 6)

trie_filter_free($trie);
```

### 常驻内存框架中使用（如 webman）

```php
<?php
// 进程启动时加载一次，后续复用
$trie = trie_filter_load('/path/to/sensitive.tree');

// 在控制器/服务中使用
$results = trie_filter_search_all($trie, $userContent);
```

## PHP 函数列表

| 函数 | 说明 | 返回值 |
|------|------|--------|
| `trie_filter_new()` | 创建空 Trie 树 | resource/null |
| `trie_filter_store($res, $word)` | 添加关键词 | bool |
| `trie_filter_delete($res, $word)` | 删除关键词 | bool |
| `trie_filter_save($res, $path)` | 保存到文件 | bool |
| `trie_filter_load($path)` | 从文件加载 | resource/null |
| `trie_filter_read($bin)` | 从二进制字符串加载 | resource/null |
| `trie_filter_write($res)` | 导出为二进制字符串 | string/false |
| `trie_filter_search($res, $text)` | 搜索第一个匹配 | [offset, length] 或 [] |
| `trie_filter_search_all($res, $text)` | 搜索所有匹配 | [[offset, length], ...] |
| `trie_filter_free($res)` | 释放资源 | bool |

## 项目文件

| 文件 | 说明 |
|------|------|
| `CMakeLists.txt` | cmake 构建配置 |
| `trie_filter.c` | 扩展主实现（PHP 8.1+ API） |
| `php_trie_filter.h` | 扩展头文件 |
| `trie_filter.php` | IDE 自动补全 stub |
| `test.php` | 测试脚本 |
| `test_zh.php` | 中文测试脚本 |

## 升级历史

- **v1.0 20260331** — 适配 PHP 8.1+，改用 cmake 构建，修复内存泄漏、double-free、二进制安全等问题
- **2017-08-08** — 同时支持 PHP 5 & PHP 7，新增 `trie_filter_read`、`trie_filter_write`、`trie_filter_delete`
- **2013-06-23** — 新增 `trie_filter_search_all`，修复内存泄漏

## License

Apache License 2.0