# Въведение
Greph е енджин за търсене и рефакториране на дървета с изходен код, написан изцяло на PHP. Той поддържа три свързани режима:

- **Текстово търсене** с изход, съвместим с grep, и удобство като при ripgrep.
- **Търсене в AST** със структурни шаблони във формат PHP и метапроменливи.
- **Пренаписване на AST** със структурно рефакториране, което запазва форматирането.

Освен това включва предварително заредени индексирани режими за текстови и AST задачи, политики за обновяване според жизнения цикъл, набори от индекси с манифест и обвивки за съвместимост с `rg` / `sg` за инструменти и агентни среди.

## Защо съществува Greph

PHP приложенията и агентите, които се нуждаят от бързо търсене в код, обикновено стартират нативни инструменти от командния ред (`grep`, `ripgrep`, `ast-grep`). Така губят преносимост и усложняват внедряването. При структурното търсене и пренаписване е още по-неудобно: обикновено се налага да напуснат изцяло процеса на PHP.

Greph премахва тази празнина. Вашият код на PHP може да извършва текстови търсения, структурни съвпадения и рефакториращи пренаписвания, като използва само стандартната библиотека и `nikic/php-parser`. Изходът и кодовете за изход са съвместими с каноничните инструменти, така че съществуващите скриптове и агенти не се нуждаят от промени.

## Какво прави

- Търсене на точни низове и по регулярни изрази с режими за цели думи, съвпадение без значение от регистъра, контекст, брой съвпадения и само файлове
- Структурно търсене в AST на PHP с `$VAR`, `$$$VARIADIC` и повтарящи се метапроменливи
- Пренаписване на AST със запазено форматиране, с режими за пробно изпълнение, интерактивна работа и запис
- Предварително заредени текстови индекси (триграми и postings за идентификатори) за повтарящи се задачи
- Предварително зареден индекс на факти в AST и кеширано търсене в AST за повтарящи се структурни заявки
- Предварително заредени индекси с управление на жизнения цикъл: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Търсене в няколко индекса и наименувани набори в предварително заредени текстови хранилища, хранилища с факти в AST и кеширани AST хранилища
- Диагностика на планировчика с `--trace-plan` и обозначаване на произхода на индекса при предварително заредено търсене
- Обвивки за съвместимост на ripgrep и ast-grep CLI, използващи същия енджин
- Паралелен работен пул на базата на pcntl с резервен режим в един процес
- Обхождане на файлове с поддръжка на gitignore и `.grephignore`, както и откриване на двоични файлове

## Какви са изискванията

- PHP 8.2 или по-нова версия
- `ext-json`, `ext-ctype` и `ext-tokenizer`, активирани в почти всяка компилация на PHP
- `ext-zlib` за кешираното хранилище на AST (`greph-index ast-cache`)
- `nikic/php-parser` (единствената зависимост на Composer)

Основните текстови и AST функции работят изцяло на PHP. Незадължителните сравнения в бенчмаркове зависят от външни инструменти като `rg`, `grep` и `sg`, но за работата на самия Greph те не са необходими. Паралелните сканирания използват `ext-pcntl`, когато е налично, и безпроблемно преминават към изпълнение в един процес, когато не е. В [Хостове с ограничени процеси](https://greph.inline0.dev/bg/docs/advanced/process-restricted-hosts) са разгледани хостове, които забраняват `proc_open()` и `shell_exec()`.

## Кратък пример

Изпълнимите файлове на `vendor/bin` изискват Greph 0.2.3 или по-нова версия, когато Greph е инсталиран като зависимост на проекта ви.

```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/bg/docs/getting-started), след което разгледайте [CLI](https://greph.inline0.dev/bg/docs/cli) и [API](https://greph.inline0.dev/bg/docs/api) за останалите възможности. Разделите [Режими](https://greph.inline0.dev/bg/docs/modes/text), [Индексиране](https://greph.inline0.dev/bg/docs/indexed/text) и [Съвместимост](https://greph.inline0.dev/bg/docs/compatibility/rg) разглеждат подробно конкретни работни процеси.