# 소개
Greph는 소스 트리를 위한 순수 PHP 검색 및 리팩터링 엔진입니다. 서로 연관된 세 가지 모드를 제공합니다:

- grep 호환 출력과 ripgrep 스타일의 사용성을 갖춘 **텍스트 검색**.
- PHP 구조 패턴과 메타변수를 사용하는 **AST 검색**.
- 서식을 유지하는 구조 리팩터링을 제공하는 **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 이상
- 거의 모든 PHP 빌드에서 활성화되는 `ext-json`, `ext-ctype`, `ext-tokenizer`
- 캐시된 AST 저장소(`greph-index ast-cache`)를 위한 `ext-zlib`
- `nikic/php-parser` (유일한 Composer 종속 항목)

핵심 텍스트 및 AST 기능은 순수 PHP로 실행됩니다. 선택적인 벤치마크 비교에는 `rg`, `grep`, `sg` 같은 외부 도구가 필요하지만, Greph 자체는 작동에 이를 필요로 하지 않습니다. 병렬 스캔은 `ext-pcntl`를 사용할 수 있으면 사용하고, 그렇지 않으면 단일 프로세스 실행으로 원활하게 전환됩니다. `proc_open()` 및 `shell_exec()`를 허용하지 않는 호스트에 대해서는 [프로세스 제한 호스트](https://greph.inline0.dev/ko/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/ko/docs/getting-started)부터 살펴보고, 나머지 기능은 [CLI](https://greph.inline0.dev/ko/docs/cli) 및 [API](https://greph.inline0.dev/ko/docs/api)을 참조하세요. 특정 워크플로우에 관한 자세한 내용은 [모드](https://greph.inline0.dev/ko/docs/modes/text), [인덱스](https://greph.inline0.dev/ko/docs/indexed/text), [호환성](https://greph.inline0.dev/ko/docs/compatibility/rg) 섹션에서 확인할 수 있습니다.