Вступ

Переглянути як Markdown Редагувати на GitHub Документація для d105217

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(), описані в розділі Хости з обмеженням процесів.

Короткий приклад

Для виконання файлів vendor/bin потрібна версія Greph 0.2.3 або новіша, якщо Greph встановлено як залежність вашого проєкту.

Командна оболонка

# 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',
);

Почніть із розділу Початок роботи, а далі перегляньте CLI і API, щоб ознайомитися з рештою можливостей. У розділах Режими, Індексований пошук і Сумісність докладно описано окремі сценарії роботи.