# PHP API

## `Greph\Greph`

A `Greph\Greph` osztály a statikus belépési pont. Minden keresési, átírási és indexelési műveletet elérhetővé tesz. Minden metódus egyetlen útvonalat vagy útvonalak listáját fogadja.

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

### `walk`

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

A `$paths` feloldása abszolút fájlútvonalak lapos `FileList` formátumára. Figyelembe veszi a gitignore-t, a `.grephignore` értékét, a fájltípus-szűrőket, a globmintákat, a rejtett fájlok bevonását, a szimbolikus hivatkozások követését, a bináris fájlok felismerését és a maximális fájlméret korlátját.

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

Szöveges keresést futtat, és `list<TextFileResult>` értéket ad vissza. Minden `TextFileResult` tartalmazza a fájl útvonalát és a `TextMatch` objektumok listáját (sor, oszlop, tartalom, rögzített értékek, opcionális környezet).

```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";
    }
}
```

Ha a `jobs > 1` értéke igaz, és a fájlok száma meghaladja a munkafolyamat-küszöböt, a `searchText` automatikusan egy `WorkerPool` számára osztja ki a vizsgálatot. Egyébként a folyamaton belül fut.

---

### `searchAst`

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

Strukturális AST-keresést futtat, és `list<AstMatch>` értéket ad vissza. A mintákat PHP forrásként kell megadni, `$VAR` és `$$$VARIADIC` metavaltozókkal. Minden `AstMatch` tartalmazza a fájlt, a rögzített `PhpParser\Node` elemet, a rögzített értékeket, a kezdő és záró sort, a bájteltolásokat, valamint az illeszkedő forrásrészletet.

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

Strukturális átírást futtat, és `list<RewriteResult>` értéket ad vissza. Minden `RewriteResult` tartalmazza a fájl útvonalát, az eredeti tartalmat, az átírt tartalmat és a cserék számát. Az átírás megőrzi a formázást: csak az illeszkedő csomópontok tartományait cseréli ki, a fájl többi része változatlan marad.

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

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

A homlokzat nem ír lemezre; a hívó dönti el, alkalmazza-e a módosításokat. A CLI alkalmazza őket, kivéve, ha a `--dry-run` vagy a `--interactive` be van állítva.

---

### Indexelt szöveges keresés

#### `buildTextIndex`

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

Új trigram- és azonosító-előfordulási indexet épít a `$rootPath` számára. Az index a `$indexPath` helyre kerül (alapértelmezés szerint `$rootPath/.greph-index`). A `$lifecycle` értéke lehet `static`, `manual-refresh`, `opportunistic-refresh` vagy `strict-stale-check`. `IndexBuildResult` értéket ad vissza, amely tartalmazza a fájlok és trigramok számát, valamint a hozzáadott, frissített, törölt és változatlan elemek számát.

#### `refreshTextIndex`

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

Meglévő szöveges index fokozatos frissítése. A fájlokat újra hasheli, és csak a módosult bejegyzéseket írja át.

#### `searchTextIndexed`

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

Szöveges keresés futtatása a bemelegített indexen. Futásidejű hibával tér vissza, ha az index nem létezik (előbb hívja meg a `buildTextIndex` függvényt). A `searchText` formátumával pontosan megegyező `list<TextFileResult>` értéket ad vissza.

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

Bemelegített szöveges keresés futtatása több szöveges indexkönyvtárban. A Greph minden megfelelő indexben keres, abszolút fájlútvonal alapján kiszűri a duplikátumokat, és csak azokra az útvonalakra tér vissza a natív vizsgálathoz, amelyek kívül esnek az összes megadott index gyökérkönyvtárán.

#### `loadIndexSet`

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

Indexkészlet-manifeszt betöltése; alapértelmezés szerint az aktuális munkakönyvtárban található `.greph-index-set.json` fájlból.

#### `searchTextIndexedSet`

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

A kiválasztott `text` bejegyzések feloldása az indexkészlet-manifesztből, majd a `searchTextIndexedMany` művelettel egyenértékű futtatás.

---

### Indexelt AST-keresés

#### `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-tényindex építése vagy fokozatos frissítése. Alapértelmezés szerint a kinyert tényeket a `$rootPath/.greph-ast-index` helyre menti.

#### `searchAstIndexed`

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

A tényindex segítségével leszűkíti a jelölteket, majd a forrás alapján újra ellenőrzi az egyezéseket. A `searchAst` értékével azonos formátumú `list<AstMatch>` értéket ad vissza.

#### `searchAstIndexedMany`

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

Bemelegített AST-ténykeresés futtatása több AST-indexkönyvtárban.

#### `searchAstIndexedSet`

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

A kiválasztott `ast-index` bejegyzések feloldása az indexkészlet-manifesztből, majd a `searchAstIndexedMany` művelettel egyenértékű futtatás.

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

A gyorsítótárazott, elemzett fákat tároló tár építése vagy fokozatos frissítése. Alapértelmezés szerint a sorosított fákat a `$rootPath/.greph-ast-cache` helyre menti.

#### `searchAstCached`

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

AST-keresés futtatása a gyorsítótárazott elemzett fákon, az elemző teljes kihagyásával. A `searchAst` értékével azonos formátumú `list<AstMatch>` értéket ad vissza.

#### `searchAstCachedMany`

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

Bemelegített, gyorsítótárazott AST-keresés futtatása több gyorsítótár-könyvtárban.

#### `searchAstCachedSet`

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

A kiválasztott `ast-cache` bejegyzések feloldása az indexkészlet-manifesztből, majd a `searchAstCachedMany` művelettel egyenértékű futtatás.

---

## `Greph\Text\TextSearchOptions`

Csak olvasható beállításokat tartalmazó objektum szöveges kereséshez.

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

Érvényesítés:

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

Ha külön szeretné bejárni a fájlfát, a megfelelő `WalkOptions` levezetéséhez használja a `walkOptions()` értékét.

A `tracePlan` értékét a bemelegített indexelt keresők használják, a `greph-index` CLI folyamat pedig a tervező diagnosztikai üzeneteit a `stderr` helyre írja. Maga a natív `searchText` nem használja.

---

## `Greph\Ast\AstSearchOptions`

Csak olvasható beállításokat tartalmazó objektum AST-kereséshez és átíráshoz.

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

Az AST-mód alapértelmezett fájltípus-szűrője: `php`. Ha a `skipParseErrors` értéke `true` (ez az alapértelmezés), az elemzési hibát okozó fájlokat a rendszer csendben kihagyja; állítsa `false` értékre, ha kivételként szeretné megkapni az elemzési hibákat. A `tracePlan` értékét a bemelegített AST-keresők, a `greph-index ast-index|ast-cache search` értékét pedig a jelöltcsökkentési diagnosztika kiírása használja.

---

## `Greph\Walker\WalkOptions`

Csak olvasható beállításokat tartalmazó objektum a fájlbejáróhoz.

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

Névvel ellátott fájltípusok feloldása kiterjesztéslistákra. Beépített aliasok:

| Alias | Kiterjesztések |
|---|---|
| `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']);
```

---

## Eredményobjektumok

### `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` és `AstCacheBuildResult` ugyanezt a formát követi, rendre `factCount` és `cachedTreeCount` behelyettesítésével.

---

## Kivételek

A Greph három típusos kivételt dob, mindegyiket a `Greph\Exceptions` tartalmazza:

| Kivétel | Mikor dobódik |
|---|---|
| `WalkerException` | Fájlrendszerhibák bejárás közben (hiányzó útvonal, nem olvasható könyvtár) |
| `PatternException` | Érvénytelen reguláris kifejezés vagy AST-minta |
| `ParseException` | A PHP forrása nem volt feldolgozható (csak akkor, ha `skipParseErrors: false`) |

Az indexelt keresési metódusok `\RuntimeException` kivételt dobnak, ha a kért helyen nincs index. A `greph-index` CLI egy `--fallback scan` beállítást biztosít, amely elkapja ezeket, és helyette index nélküli keresést végez.