PHP API

Markdown으로 보기 GitHub에서 수정 문서 위치 d105217

`Greph\Greph`

Greph\Greph 클래스는 정적 진입점입니다. 모든 검색, 재작성 및 인덱스 작업을 제공합니다. 모든 메서드는 단일 경로나 경로 목록을 받습니다.

PHP

use Greph\Greph;

`walk`

PHP

public static function walk(string|array $paths, ?WalkOptions $options = null): FileList

$paths을 절대 파일 경로로 구성된 평면 FileList로 해석합니다. gitignore, .grephignore, 파일 유형 필터, glob 패턴, 숨김 파일 포함, 심볼릭 링크 추적, 바이너리 감지 및 최대 파일 크기 제한을 적용합니다.

PHP

use Greph\Walker\WalkOptions;
use Greph\Walker\FileTypeFilter;

$files = Greph::walk('src', new WalkOptions(
    fileTypeFilter: new FileTypeFilter(['php']),
));

foreach ($files->paths() as $path) {
    echo "$path\n";
}

`searchText`

PHP

public static function searchText(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
): array

텍스트 검색을 실행하고 list<TextFileResult>을 반환합니다. 각 TextFileResult에는 파일 경로와 TextMatch 객체 목록(줄, 열, 내용, 캡처, 선택적 컨텍스트)이 포함됩니다.

PHP

use Greph\Greph;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(
        fixedString: true,
        caseInsensitive: true,
        beforeContext: 1,
        afterContext: 1,
        jobs: 4,
    ),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

jobs > 1이 설정되어 있고 파일 수가 작업자 임계값을 넘으면 searchText이 자동으로 스캔을 WorkerPool에 전달합니다. 그렇지 않으면 프로세스 내에서 실행됩니다.

`searchAst`

PHP

public static function searchAst(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

구조적 AST 검색을 실행하고 list<AstMatch>을 반환합니다. 패턴은 PHP 소스로 작성하며 $VAR 및 $$$VARIADIC 메타변수를 사용합니다. 각 AstMatch에는 파일, 캡처된 PhpParser\Node, 캡처 정보, 시작 및 종료 줄과 바이트 오프셋, 일치한 소스 부분이 포함됩니다.

PHP

use Greph\Greph;
use Greph\Ast\AstSearchOptions;

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

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

`rewriteAst`

PHP

public static function rewriteAst(
    string $searchPattern,
    string $rewritePattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

구조적 재작성을 실행하고 list<RewriteResult>을 반환합니다. 각 RewriteResult에는 파일 경로, 원본 콘텐츠, 재작성된 콘텐츠 및 대체 횟수가 포함됩니다. 재작성은 형식을 보존합니다. 일치한 노드 범위만 교체하고 나머지 파일은 그대로 둡니다.

PHP

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

foreach ($rewrites as $result) {
    if ($result->changed()) {
        file_put_contents($result->file, $result->rewrittenContents);
    }
}

파사드는 디스크에 쓰지 않으며 변경 사항을 적용할지는 호출자가 결정합니다. CLI은 --dry-run 또는 --interactive가 설정되지 않은 경우 변경 사항을 적용합니다.

인덱싱된 텍스트 검색

`buildTextIndex`

PHP

public static function buildTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

$rootPath용 새 트라이그램 및 식별자 포스팅 인덱스를 빌드합니다. 인덱스는 $indexPath에 저장되며 기본값은 $rootPath/.greph-index입니다. $lifecycle은 static, manual-refresh, opportunistic-refresh 또는 strict-stale-check일 수 있습니다. 파일 수, 트라이그램 수 및 추가/업데이트/삭제/변경 없음 항목 수가 포함된 IndexBuildResult을 반환합니다.

`refreshTextIndex`

PHP

public static function refreshTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

기존 텍스트 인덱스를 점진적으로 새로 고칩니다. 파일을 다시 해시하고 변경된 항목만 다시 씁니다.

`searchTextIndexed`

PHP

public static function searchTextIndexed(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $indexPath = null,
): array

준비된 인덱스에서 텍스트 검색을 실행합니다. 인덱스가 없으면 런타임 오류를 반환합니다(먼저 buildTextIndex을 호출하세요). searchText와 정확히 같은 형식의 list<TextFileResult>을 반환합니다.

PHP

Greph::buildTextIndex('.');
$results = Greph::searchTextIndexed('function', 'src');

`searchTextIndexedMany`

PHP

public static function searchTextIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?TextSearchOptions $options = null,
): array

여러 텍스트 인덱스 디렉터리에서 준비된 텍스트 검색을 실행합니다. Greph은 적용 가능한 각 인덱스를 검색하고, 절대 파일 경로를 기준으로 중복을 제거하며, 제공된 모든 인덱스 루트 밖의 경로에 대해서만 기본 스캔으로 대체합니다.

`loadIndexSet`

PHP

public static function loadIndexSet(?string $manifestPath = null): IndexSet

현재 작업 디렉터리의 .greph-index-set.json을 기본값으로 사용해 인덱스 세트 매니페스트를 불러옵니다.

`searchTextIndexedSet`

PHP

public static function searchTextIndexedSet(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

인덱스 세트 매니페스트에서 선택한 text 항목을 해석하고 searchTextIndexedMany과 동등한 작업을 실행합니다.

인덱싱된 AST 검색

`buildAstIndex` / `refreshAstIndex`

PHP

public static function buildAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult
public static function refreshAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult

AST 사실 인덱스를 빌드하거나 점진적으로 새로 고칩니다. 추출한 사실은 기본적으로 $rootPath/.greph-ast-index에 저장합니다.

`searchAstIndexed`

PHP

public static function searchAstIndexed(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

사실 인덱스를 사용해 후보를 좁힌 후 소스와 대조해 일치 여부를 다시 확인합니다. searchAst과 동일한 list<AstMatch> 형식으로 반환합니다.

`searchAstIndexedMany`

PHP

public static function searchAstIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

여러 AST 인덱스 디렉터리에서 준비된 AST 사실 검색을 실행합니다.

`searchAstIndexedSet`

PHP

public static function searchAstIndexedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

인덱스 세트 매니페스트에서 선택한 ast-index 항목을 해석하고 searchAstIndexedMany과 동등한 작업을 실행합니다.

`buildAstCache` / `refreshAstCache`

PHP

public static function buildAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult
public static function refreshAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult

캐시된 파스 트리 저장소를 빌드하거나 점진적으로 새로 고칩니다. 직렬화된 트리는 기본적으로 $rootPath/.greph-ast-cache에 저장합니다.

`searchAstCached`

PHP

public static function searchAstCached(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

캐시된 파스 트리에서 AST 검색을 실행해 파서를 완전히 건너뜁니다. searchAst과 동일한 list<AstMatch> 형식으로 반환합니다.

`searchAstCachedMany`

PHP

public static function searchAstCachedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

여러 캐시 디렉터리에서 준비된 캐시 AST 검색을 실행합니다.

`searchAstCachedSet`

PHP

public static function searchAstCachedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

인덱스 세트 매니페스트에서 선택한 ast-cache 항목을 해석하고 searchAstCachedMany과 동등한 작업을 실행합니다.

`Greph\Text\TextSearchOptions`

텍스트 검색용 읽기 전용 옵션 객체입니다.

PHP

new TextSearchOptions(
    bool $fixedString = false,
    bool $caseInsensitive = false,
    bool $wholeWord = false,
    bool $invertMatch = false,
    ?int $maxCount = null,
    int $beforeContext = 0,
    int $afterContext = 0,
    bool $countOnly = false,
    bool $filesWithMatches = false,
    bool $filesWithoutMatches = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $showLineNumbers = true,
    bool $showFileNames = true,
)

검증:

jobs >= 1
beforeContext, afterContext >= 0
maxCount === null || maxCount >= 1

파일 트리를 별도로 탐색하려면 walkOptions()을 사용해 일치하는 WalkOptions을 가져오세요.

tracePlan은 준비된 인덱스 검색기가 사용하며, greph-index CLI 흐름에서는 플래너 진단을 stderr으로 출력하는 데 사용됩니다. 기본 searchText 자체에서는 사용하지 않습니다.

`Greph\Ast\AstSearchOptions`

AST 검색 및 재작성용 읽기 전용 옵션 객체입니다.

PHP

new AstSearchOptions(
    string $language = 'php',
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $skipParseErrors = true,
    bool $dryRun = false,
    bool $interactive = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
)

AST 모드의 기본 파일 유형 필터는 php입니다. skipParseErrors이 true(기본값)이면 파싱에 실패한 파일은 조용히 건너뜁니다. 파싱 오류를 예외로 표시하려면 false으로 변경하세요. tracePlan는 준비된 AST 검색기가 사용하며, greph-index ast-index|ast-cache search는 후보 제거 진단을 출력하는 데 사용됩니다.

`Greph\Walker\WalkOptions`

파일 워커용 읽기 전용 옵션 객체입니다.

PHP

new WalkOptions(
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = false,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
)

`Greph\Walker\FileTypeFilter`

이름이 지정된 파일 유형을 확장자 목록으로 해석합니다. 기본 제공 별칭:

별칭	확장자
`css`	`css`, `sass`, `scss`
`html`	`htm`, `html`, `phtml`
`js`	`cjs`, `js`, `mjs`
`json`	`json`
`md`	`markdown`, `md`
`php`	`inc`, `php`, `php3`, `php4`, `php5`, `php7`, `php8`, `phpt`, `phtml`
`txt`	`txt`
`ts`	`ts`, `tsx`
`xml`	`xml`
`yaml`	`yaml`, `yml`

PHP

new FileTypeFilter(includeTypes: ['php'], excludeTypes: ['md']);

결과 객체

`Greph\Text\TextFileResult`

PHP

final readonly class TextFileResult
{
    public string $file;
    /** @var list<TextMatch> */
    public array $matches;

    public function matchCount(): int;
    public function hasMatches(): bool;
}

`Greph\Text\TextMatch`

PHP

final readonly class TextMatch
{
    public string $file;
    public int $line;
    public int $column;
    public string $content;
    public string $matchedText;
    /** @var array<int|string, string> */
    public array $captures;
    /** @var list<array{line: int, content: string}> */
    public array $beforeContext;
    /** @var list<array{line: int, content: string}> */
    public array $afterContext;
}

`Greph\Ast\AstMatch`

PHP

final readonly class AstMatch
{
    public string $file;
    public PhpParser\Node $node;
    /** @var array<string, mixed> */
    public array $captures;
    public int $startLine;
    public int $endLine;
    public int $startFilePos;
    public int $endFilePos;
    public string $code;
}

`Greph\Ast\RewriteResult`

PHP

final readonly class RewriteResult
{
    public string $file;
    public string $originalContents;
    public string $rewrittenContents;
    public int $replacementCount;

    public function changed(): bool;
}

`Greph\Index\IndexBuildResult`

PHP

final readonly class IndexBuildResult
{
    public string $rootPath;
    public string $indexPath;
    public int $fileCount;
    public int $trigramCount;
    public int $addedFiles;
    public int $updatedFiles;
    public int $deletedFiles;
    public int $unchangedFiles;
}

AstIndexBuildResult와 AstCacheBuildResult은 각각 factCount와 cachedTreeCount로 대체된 동일한 형식을 따릅니다.

예외

Greph은 모두 Greph\Exceptions에 속하는 세 가지 유형의 예외를 발생시킵니다.

예외	발생하는 경우
`WalkerException`	순회 중 파일 시스템 오류(경로 누락, 디렉터리를 읽을 수 없음)
`PatternException`	잘못된 정규식 또는 AST 패턴
`ParseException`	PHP 소스를 파싱할 수 없음(`skipParseErrors: false`인 경우에만)

요청한 위치에 인덱스가 없으면 인덱스 검색 메서드는 \RuntimeException을 발생시킵니다. greph-index CLI에는 이를 포착하고 대신 비인덱스 검색으로 대체하는 --fallback scan 옵션이 있습니다.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

인덱싱된 텍스트 검색

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

인덱싱된 AST 검색

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter