Въведение

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, когато е налично, и безпроблемно преминават към изпълнение в един процес, когато не е. В Хостове с ограничени процеси са разгледани хостове, които забраняват 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

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 за останалите възможности. Разделите Режими, Индексиране и Съвместимост разглеждат подробно конкретни работни процеси.