Введение

Просмотреть как 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. Вывод и коды завершения совместимы с каноническими инструментами, поэтому существующие скрипты и агенты менять не нужно.

Возможности

Поиск по фиксированной строке и регулярному выражению, с поиском целых слов, без учета регистра, с контекстом, подсчетом и режимом вывода только файлов
Структурный поиск по 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(), описаны в разделе Хосты с ограничением процессов.

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

Исполняемым файлам 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, чтобы ознакомиться с остальными возможностями. В разделах Режимы, Индексирование и Совместимость подробно описаны конкретные рабочие процессы.