# Введение
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 с сохранением формата в режимах предварительного просмотра, интерактивного выбора и записи
- Прогретые текстовые индексы (триграммы и списки вхождений идентификаторов) для повторяющихся задач
- Прогретый индекс фактов 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`, параллельное сканирование использует его, а в противном случае корректно переходит к однопроцессному выполнению. Хосты, запрещающие `proc_open()` и `shell_exec()`, описаны в разделе [Хосты с ограничением процессов](https://greph.inline0.dev/ru/docs/advanced/process-restricted-hosts).

## Быстрый пример

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