# Вступ
Greph — рушій пошуку та рефакторингу дерев вихідного коду, написаний лише на PHP. Він підтримує три пов’язані режими:

- **Текстовий пошук** із виводом, сумісним із grep, і зручністю ripgrep.
- **Пошук AST** зі структурними шаблонами PHP і метазмінними.
- **Перезапис AST** зі структурним рефакторингом, що зберігає форматування.

Також доступні індексовані режими з прогріванням для текстового й AST-пошуку, політики оновлення з урахуванням життєвого циклу, прогріті набори індексів на основі маніфестів, а також обгортки сумісності `rg` і `sg` для інструментів та агентів.

## Навіщо потрібен Greph

Застосунки PHP й агенти, яким потрібен швидкий пошук у коді, зазвичай запускають нативні інструменти через оболонку (`grep`, `ripgrep`, `ast-grep`), втрачаючи переносність і ускладнюючи розгортання. Структурний пошук і перезапис — ще складніше: зазвичай для цього доводиться повністю виходити з процесу PHP.

Greph усуває цю прогалину. Ваш код PHP може виконувати текстовий пошук, структурне зіставлення та рефакторинг із перезаписом, використовуючи лише стандартну бібліотеку й `nikic/php-parser`. Формат виводу та коди завершення сумісні з канонічними інструментами, тому наявні скрипти й агенти не потрібно змінювати.

## Що він робить

- Пошук тексту за фіксованим рядком і регулярним виразом із режимами цілого слова, без урахування регістру, контексту, підрахунку та лише файлів
- Структурний пошук PHP за AST із `$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/uk/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/uk/docs/getting-started), а далі перегляньте [CLI](https://greph.inline0.dev/uk/docs/cli) і [API](https://greph.inline0.dev/uk/docs/api), щоб ознайомитися з рештою можливостей. У розділах [Режими](https://greph.inline0.dev/uk/docs/modes/text), [Індексований пошук](https://greph.inline0.dev/uk/docs/indexed/text) і [Сумісність](https://greph.inline0.dev/uk/docs/compatibility/rg) докладно описано окремі сценарії роботи.