시작하기
설치
Composer을 통해 Greph을 설치하세요.
composer require greph/greph
이렇게 하면 라이브러리와 네 가지 실행 파일이 vendor/bin/에 설치됩니다.
greph: 네이티브 텍스트 검색, AST 검색 및 AST 재작성greph-index: 워밍된 텍스트 인덱스, AST 팩트 인덱스 및 캐시된 AST 검색rg: ripgrep 스타일 호환 래퍼sg: ast-grep 스타일 호환 래퍼
Greph 0.2.3하기 때문에 이 실행 파일은 프로젝트의 vendor/bin/에서 작동합니다. 이전 릴리스에서는 Greph 저장소의 복제본 안에 있는 Composer 오토로더만 찾았으므로, 해당 버전 이상을 사용해야 합니다.
composer require greph/greph:^0.2.3
요구 사항
- PHP 8.2+ readonly 클래스, enum, first-class callable 구문, 생성자 프로모션 지원
- ext-json JSON 출력 및 디스크 인덱스 페이로드용
- ext-ctype 패턴 및 옵션 파싱용
- ext-tokenizer PHP-Parser 및 AST 사전 필터용
- ext-zlib 캐시된 AST 저장소(
greph-index ast-cache)용 - nikic/php-parser (Composer 종속 항목으로 자동 설치됨)
ext-json, ext-ctype, ext-tokenizer는 거의 모든 PHP 빌드에서 활성화되어 있습니다. 현재 composer.json는 ext-json만 선언하므로(#5), 다른 항목 중 하나가 없어도 Composer는 경고하지 않습니다.
선택 사항:
- 병렬 스캔에는 ext-pcntl이 필요합니다. Greph가 없으면 단일 프로세스 실행으로 원활하게 전환됩니다.
- 벤치마크 비교를 위한 외부
rg,grep,sg바이너리입니다. 런타임에는 필요하지 않습니다.
검색, 재작성 및 인덱싱 과정에서는 proc_open() 또는 shell_exec()를 호출하지 않습니다. 병렬 스캔만 프로세스를 분기하며, pcntl_fork()가 없으면 단일 프로세스로 대체 실행됩니다. proc_open(), shell_exec() 또는 pcntl_fork()를 비활성화하는 호스트는 프로세스 제한 호스트를 참조하세요.
첫 텍스트 검색
Greph의 기본 모드는 grep 호환 텍스트 검색입니다:
vendor/bin/greph -F "function" src
출력은 grep, ripgrep 및 대부분의 편집기 통합 기능이 기대하는 표준 file:line:content 형식을 사용합니다.
src/Greph.php:41: public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50: public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81: public static function buildTextIndex(
대소문자를 구분하지 않는 일치는 -i, 전체 단어 일치는 -w, 개수 표시에는 -c, 파일 경로만 표시하려면 -l, 앞뒤 두 줄의 컨텍스트를 표시하려면 -C 2 등을 추가하세요. 전체 목록은 참조CLI에서 확인할 수 있습니다.
첫 AST 검색
구조 검색으로 전환하려면 -p와 PHP 형태의 패턴을 전달하세요:
vendor/bin/greph -p 'new $CLASS()' src
$CLASS는 모든 클래스 이름을 캡처하는 메타변수입니다. new $CLASS() 패턴은 클래스나 서식, 주석에 관계없이 인수가 없는 모든 new 식과 일치합니다. 인수가 무엇이든 호출과 일치시키려면 new $CLASS($$$ARGS)를 사용하세요.
각 AST 일치 항목은 파일, 시작 줄, 일치한 코드 순으로 출력됩니다:
src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()
그 밖의 유용한 패턴:
# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src
# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src
전체 패턴 구문은 모드 / AST 검색을 참조하세요.
첫 재작성
AST 검색을 재작성으로 전환하려면 -r를 추가하세요:
# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src
# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
재작성은 일치 항목 바깥의 서식을 유지합니다. 일치한 노드만 교체되며 주변 공백, 들여쓰기, 주석은 그대로 유지됩니다. 일치한 노드 자체는 템플릿에서 새로 출력되므로 내부 레이아웃이 정규화되고, 노드 안의 주석은 사라질 수 있습니다. 자세한 내용은 모드 / 재작성을 참조하세요.
PHP API
정적 Greph\Greph 파사드는 CLI와 같은 작업을 제공합니다:
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;
$results = Greph::searchText(
'function',
'src',
new TextSearchOptions(fixedString: true, caseInsensitive: true),
);
foreach ($results as $file) {
foreach ($file->matches as $match) {
echo "{$file->file}:{$match->line}:{$match->content}\n";
}
}
$matches = Greph::searchAst(
'new $CLASS()',
'src',
new AstSearchOptions(),
);
foreach ($matches as $match) {
echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}
전체 기능은 API에서 다룹니다.
인덱스 검색
반복 작업은 미리 준비된 인덱스를 활용하면 빨라집니다. 한 번 빌드한 다음 여러 번 쿼리하세요:
# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .
# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src
# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
기본적으로 인덱스는 프로젝트 루트의 .greph-index, .greph-ast-index, .greph-ast-cache에 저장됩니다.
자주 변경되는 트리에서는 미리 준비된 인덱스를 모두 똑같이 취급하는 대신 수명 주기 프로필을 선택하세요:
vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
--lifecycle opportunistic-refresh \
--auto-refresh-max-files 32 \
--auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh
일반적인 패턴은 다음과 같습니다:
- 안정적인 기준 인덱스는
static로 유지 - 자주 변경되는 오버레이는
opportunistic-refresh로 유지 - 오래된 상태의 동작은
stats --dry-refresh로 검사
여러 인덱스를 사용한 검색
한 명령으로 미리 준비된 여러 인덱스를 검색할 수 있습니다:
vendor/bin/greph-index search -F "apply_filters" . \
--index-dir wordpress/.greph-index \
--index-dir wp-content/plugins/my-plugin/.greph-index \
--show-index-origin
vendor/bin/greph-index ast-index search 'new $CLASS()' . \
--index-dir wordpress/.greph-ast-index \
--index-dir wp-content/plugins/my-plugin/.greph-ast-index \
--show-index-origin
이름이 지정된 인덱스 세트
이 작업을 반복한다면 구성을 .greph-index-set.json에 저장하고, 플래그를 반복해서 지정하는 대신 세트 하위 명령을 사용하세요:
vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
플래너 추적
미리 준비된 검색이 후보를 어떻게 좁히는지 보려면 --trace-plan를 추가하세요:
vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .
전체 사전 준비 워크플로우는 인덱스 / 텍스트 및 인덱스 / AST를 참조하세요.
호환성 래퍼
이미 ripgrep 또는 ast-grep를 사용하는 도구나 에이전트가 있다면 래퍼를 추가하세요:
vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php
두 래퍼 모두 같은 엔진을 재사용하며 업스트림 바이너리를 대상으로 프로브 검증을 거쳤습니다. 검증된 기능은 호환성 / rg 및 호환성 / sg에 문서화되어 있고, 생성된 기능 매트릭스에도 수록되어 있습니다.
구성
Greph는 디스크에 저장하는 두 가지 규칙을 따릅니다:
- 기본적으로
.gitignore를 따릅니다. 사용하지 않으려면--no-ignore를 전달하세요. .grephignore는.gitignore와 같은 구문을 사용해 그 위에 적용됩니다. 버전 관리에 포함하고 싶지 않은 도구별 제외 항목에 유용합니다.
선택한 루트의 기본 인덱스 디렉터리는 .greph-index, .greph-ast-index, .greph-ast-cache입니다. 모든 greph-index 하위 명령에서 --index-dir로 재정의하거나, 반복 가능한 다중 인덱스 구성에는 .greph-index-set.json를 사용하세요.