# PHP API

## `Greph\Greph`

`Greph\Greph` sınıfı statik giriş noktasıdır. Tüm arama, yeniden yazma ve dizin işlemlerini sunar. Tüm yöntemler tek bir yolu veya yol listesini kabul eder.

```php
use Greph\Greph;
```

### `walk`

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

`$paths` değerini mutlak dosya yollarından oluşan düz bir `FileList` yapısına dönüştürür. gitignore, `.grephignore`, dosya türü filtreleri, glob desenleri, gizli dosyaları dahil etme, sembolik bağlantıları izleme, ikili dosya algılama ve en büyük dosya boyutu sınırını dikkate alır.

```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
```

Metin araması yapar ve bir `list<TextFileResult>` döndürür. Her `TextFileResult`, dosya yolunu ve `TextMatch` nesnelerinin listesini (satır, sütun, içerik, yakalananlar, isteğe bağlı bağlam) sunar.

```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` etkin olduğunda ve dosya sayısı worker eşiğini aştığında `searchText` taramayı otomatik olarak bir `WorkerPool` öğesine yönlendirir. Aksi durumda işlem aynı süreçte çalışır.

---

### `searchAst`

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

Yapısal AST araması yapar ve bir `list<AstMatch>` döndürür. Desenler, `$VAR` ve `$$$VARIADIC` metavariables içeren PHP kaynak koduyla yazılır. Her `AstMatch`; dosyayı, yakalanan `PhpParser\Node` değerini, yakalananları, başlangıç ve bitiş satırları ile bayt ofsetlerini ve eşleşen kaynak dilimini içerir.

```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
```

Yapısal yeniden yazma işlemi yapar ve bir `list<RewriteResult>` döndürür. Her `RewriteResult`; dosya yolunu, özgün içeriği, yeniden yazılmış içeriği ve değiştirme sayısını sunar. Yeniden yazma biçimi korur: yalnızca eşleşen düğüm aralıkları değiştirilir; dosyanın geri kalanı olduğu gibi bırakılır.

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

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

Facade diske yazmaz; değişiklikleri uygulayıp uygulamayacağına çağıran taraf karar verir. CLI, `--dry-run` veya `--interactive` ayarlanmadığı sürece değişiklikleri uygular.

---

### Dizinlenmiş metin araması

#### `buildTextIndex`

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

`$rootPath` için yeni bir trigram + tanımlayıcı ters dizini oluşturur. Dizin, varsayılan olarak `$rootPath/.greph-index` konumunda belirlenen `$indexPath` yolunda saklanır. `$lifecycle` değeri `static`, `manual-refresh`, `opportunistic-refresh` veya `strict-stale-check` olabilir. Dosya sayısı, trigram sayısı ve eklenen/güncellenen/silinen/değişmeyen sayılarını içeren bir `IndexBuildResult` döndürür.

#### `refreshTextIndex`

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

Mevcut bir metin dizinini artımlı olarak yeniler. Dosyalar yeniden özetlenir ve yalnızca değişen girdiler yeniden yazılır.

#### `searchTextIndexed`

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

Hazır durumdaki dizinde metin araması yapar. Dizin yoksa çalışma zamanı hatası verir (önce `buildTextIndex` çağırın). `searchText` ile tam olarak aynı yapıda bir `list<TextFileResult>` döndürür.

```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
```

Birden fazla metin dizini dizininde hazır durumdaki metin aramasını çalıştırır. Greph, uygulanabilir her dizinde arama yapar, mutlak dosya yoluna göre yinelenen sonuçları tekilleştirir ve yalnızca sağlanan dizin köklerinin dışında kalan yollar için yerel taramaya geri döner.

#### `loadIndexSet`

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

Geçerli çalışma dizinindeki varsayılan `.greph-index-set.json` değerini kullanarak bir dizin kümesi manifestosu yükler.

#### `searchTextIndexedSet`

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

Dizin kümesi manifestosundaki seçili `text` girdilerini çözümler ve `searchTextIndexedMany` işleminin eşdeğerini çalıştırır.

---

### Dizinlenmiş AST araması

#### `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 olgu dizinini oluşturur veya artımlı olarak yeniler. Çıkarılan olguları varsayılan olarak `$rootPath/.greph-ast-index` konumunda saklar.

#### `searchAstIndexed`

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

Kaynak üzerinde eşleşmeleri yeniden doğrulamadan önce adayları daraltmak için olgu dizinini kullanır. `searchAst` ile aynı `list<AstMatch>` yapısını döndürür.

#### `searchAstIndexedMany`

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

Birden fazla AST dizin dizininde hazır durumdaki AST olgu aramasını çalıştırır.

#### `searchAstIndexedSet`

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

Dizin kümesi manifestosundaki seçili `ast-index` girdilerini çözümler ve `searchAstIndexedMany` işleminin eşdeğerini çalıştırır.

#### `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
```

Önbelleğe alınmış ayrıştırılmış ağaç deposunu oluşturur veya artımlı olarak yeniler. Serileştirilmiş ağaçları varsayılan olarak `$rootPath/.greph-ast-cache` konumunda saklar.

#### `searchAstCached`

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

Ayrıştırıcıyı tamamen atlayarak önbelleğe alınmış ayrıştırılmış ağaçlar üzerinde AST araması yapar. `searchAst` ile aynı `list<AstMatch>` yapısını döndürür.

#### `searchAstCachedMany`

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

Birden fazla önbellek dizininde hazır durumdaki cached-AST aramasını çalıştırır.

#### `searchAstCachedSet`

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

Dizin kümesi manifestosundaki seçili `ast-cache` girdilerini çözümler ve `searchAstCachedMany` işleminin eşdeğerini çalıştırır.

---

## `Greph\Text\TextSearchOptions`

Metin araması için salt okunur seçenekler nesnesi.

```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,
)
```

Doğrulama:

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

Dosya ağacını ayrı olarak taramak istiyorsanız, eşleşen `WalkOptions` değerini elde etmek için `walkOptions()` kullanın.

`tracePlan`, hazır durumdaki dizin arayıcıları tarafından kullanılır; `greph-index` CLI ise planlayıcı tanılamalarını `stderr` konumuna iletir. Yerel `searchText` bunu kullanmaz.

---

## `Greph\Ast\AstSearchOptions`

AST araması ve yeniden yazma için salt okunur seçenekler nesnesi.

```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 modu için varsayılan dosya türü filtresi `php` değeridir. `skipParseErrors` değeri `true` olduğunda (varsayılan), ayrıştırılamayan dosyalar sessizce atlanır; ayrıştırma hatalarının istisna olarak bildirilmesi için `false` olarak değiştirin. `tracePlan` hazır durumdaki AST arayıcıları tarafından; `greph-index ast-index|ast-cache search` ise aday eleme tanılamalarını iletmek için kullanılır.

---

## `Greph\Walker\WalkOptions`

Dosya tarayıcısı için salt okunur seçenekler nesnesi.

```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`

Adlandırılmış dosya türlerini uzantı listelerine çözümler. Yerleşik takma adlar:

| Takma ad | Uzantılar |
|---|---|
| `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']);
```

---

## Sonuç nesneleri

### `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` ve `AstCacheBuildResult` aynı yapıyı izler; sırasıyla `factCount` ve `cachedTreeCount` kullanılır.

---

## İstisnalar

Greph, tümü `Greph\Exceptions` içinde bulunan üç türlenmiş istisna fırlatır:

| İstisna | Oluşma nedeni |
|---|---|
| `WalkerException` | Tarama sırasında dosya sistemi hataları (yol bulunamadı, dizin okunamıyor) |
| `PatternException` | Geçersiz regex veya AST deseni |
| `ParseException` | PHP kaynağı ayrıştırılamadı (yalnızca `skipParseErrors: false` olduğunda) |

Dizinlenmiş arama yöntemleri, istenen konumda dizin bulunmadığında `\RuntimeException` hatası verir. CLI `greph-index`, bu hataları yakalayıp dizinsiz taramaya geri dönen bir `--fallback scan` seçeneği sunar.