# 简介
Greph是一个纯 PHP 搜索和重构引擎，用于源码树。它涵盖三种相关模式：

- **文本搜索**：输出兼容 grep，使用 ripgrep 风格的操作体验。
- **AST 搜索**：使用 PHP 结构模式和元变量。
- **AST 重写**：以保留格式的方式进行结构化重构。

它还为文本和 AST 工作负载提供预热索引模式、感知生命周期的刷新策略、由清单支持的预热索引集，以及适用于工具和智能体环境的 `rg` / `sg` 兼容包装器。

## Greph 的由来

PHP应用和智能体通常需要快速代码搜索，因此会调用原生工具（`grep`、`ripgrep`、`ast-grep`），牺牲可移植性并增加部署阻力。结构化搜索和重写更麻烦：通常需要完全离开 PHP 进程。

Greph消除了这一障碍。你的 PHP 代码只需标准库和 `nikic/php-parser`，即可执行文本搜索、结构匹配和重构重写。输出和退出代码与相应的原生工具兼容，因此现有脚本和智能体无需更改。

## 功能说明

- 固定字符串和正则表达式文本搜索，支持整词、忽略大小写、上下文、计数和仅列出文件模式
- 结构化 PHP AST 搜索，支持 `$VAR`、`$$$VARIADIC` 和重复元变量
- 保留格式的 AST 重写，支持试运行、交互和写入模式
- 用于重复工作负载的预热文本索引（三元组 + 标识符倒排表）
- 用于重复结构化查询的预热 AST 事实索引和缓存 AST 搜索
- 感知生命周期的预热索引：`static`、`manual-refresh`、`opportunistic-refresh`、`strict-stale-check`
- 可跨预热文本、AST 事实和 AST 缓存存储进行多索引及命名集合搜索
- 提供 `--trace-plan` 的规划器诊断信息，以及预热搜索的索引来源标注
- 由同一引擎支持的 ripgrep 和 ast-grep CLI 兼容包装器
- 基于 pcntl 的并行工作进程池，并在单进程模式下回退
- 支持 gitignore 和 `.grephignore`、可检测二进制文件的文件遍历器

## 运行要求

- PHP 8.2 或更高版本
- `ext-json`、`ext-ctype` 和 `ext-tokenizer`，几乎所有 PHP 构建都已启用这些扩展
- `ext-zlib`，用于缓存 AST 存储（`greph-index ast-cache`）
- `nikic/php-parser`（唯一的 Composer 依赖项）

核心文本和 AST 功能以纯 PHP 运行。可选的基准比较依赖 `rg`、`grep` 和 `sg` 等外部工具，但 Greph 本身无需这些工具即可运行。若可用，并行扫描会使用 `ext-pcntl`；否则会平稳回退到单进程执行。禁止使用 `proc_open()` 和 `shell_exec()` 的主机可参阅 [受限进程的主机](https://greph.inline0.dev/zh/docs/advanced/process-restricted-hosts)。

## 快速示例

当 Greph 作为项目依赖安装时，`vendor/bin` 可执行文件需要 Greph 0.2.3 或更高版本。

```bash
# Text search
vendor/bin/greph -F "function" src

# Structural search
vendor/bin/greph -p 'new $CLASS()' src

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
```

```php
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$matches = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true),
);

$asts = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);
```

先阅读 [入门](https://greph.inline0.dev/zh/docs/getting-started)，然后通过 [CLI](https://greph.inline0.dev/zh/docs/cli) 和 [API](https://greph.inline0.dev/zh/docs/api) 了解其余功能。[模式](https://greph.inline0.dev/zh/docs/modes/text)、[索引](https://greph.inline0.dev/zh/docs/indexed/text)和 [兼容性](https://greph.inline0.dev/zh/docs/compatibility/rg)章节深入介绍了特定工作流程。