Introdução

Greph é um mecanismo puro de pesquisa e refatoração PHP para árvores de código-fonte. Ele abrange três modos relacionados:

• Pesquisa de texto com saída compatível com grep e praticidade no estilo de ripgrep.
• Pesquisa de AST com padrões estruturais PHP e metavariáveis.
• Reescrita de AST com refatoração estrutural que preserva a formatação.

Também inclui modos indexados aquecidos para cargas de trabalho de texto e AST, políticas de atualização atentas ao ciclo de vida, conjuntos de índices aquecidos respaldados por manifestos e wrappers de compatibilidade rg / sg para ambientes de ferramentas e agentes.

Por que Greph existe

Aplicações e agentes PHP que precisam de pesquisa rápida de código geralmente recorrem a ferramentas nativas (grep, ripgrep, ast-grep), abrindo mão da portabilidade e adicionando dificuldades de implantação. A pesquisa e a reescrita estruturais são ainda mais difíceis: normalmente exigem sair completamente do processo PHP.

Greph elimina essa lacuna. Seu código PHP pode executar pesquisas de texto, correspondências estruturais e reescritas de refatoração usando apenas a biblioteca padrão e nikic/php-parser. A saída e os códigos de saída são compatíveis com as ferramentas canônicas, então os scripts e agentes existentes não precisam mudar.

O que ele faz

• Pesquisa de texto por strings literais e expressões regulares, com modos para palavras inteiras, diferenciação entre maiúsculas e minúsculas, contexto, contagem e somente arquivos
• Pesquisa estrutural de AST PHP com padrões $VAR, $$$VARIADIC e metavariáveis repetidas
• Reescrita de AST que preserva a formatação, com modos de simulação, interativo e gravação
• Índices de texto aquecidos (trigramas + listas de identificadores) para cargas de trabalho repetidas
• Índice de fatos de AST aquecido e pesquisa de AST em cache para consultas estruturais repetidas
• Índices aquecidos atentos ao ciclo de vida: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Pesquisa em vários índices e conjuntos nomeados nos armazenamentos aquecidos de texto, fatos de AST e cache de AST
• Diagnósticos do planejador com --trace-plan e identificação da origem do índice nas pesquisas aquecidas
• Wrappers de compatibilidade ripgrep e ast-grep CLI respaldados pelo mesmo mecanismo
• Conjunto de processos de trabalho paralelos baseado em pcntl, com alternativa de processo único
• Percursor de arquivos atento a gitignore e .grephignore, com detecção de arquivos binários

O que é necessário

• PHP 8.2 ou posterior
• ext-json, ext-ctype e ext-tokenizer, habilitados em quase todas as compilações de PHP
• ext-zlib para o armazenamento de AST em cache (greph-index ast-cache)
• nikic/php-parser (a única dependência de Composer)

Os recursos essenciais de texto e AST funcionam em PHP puro. As comparações opcionais de benchmark dependem de ferramentas externas como rg, grep e sg, mas o próprio Greph não precisa delas para funcionar. As varreduras paralelas usam ext-pcntl quando disponível e recorrem normalmente à execução em processo único quando não está. Hosts que proíbem proc_open() e shell_exec() são abordados em Hosts com restrições a processos.

Exemplo rápido

Os executáveis vendor/bin precisam de Greph 0.2.3 ou posterior quando Greph é instalado como dependência do seu projeto.

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

Comece por Primeiros passos e depois consulte CLI e API para conhecer os demais recursos. As seções Modos, Indexação e Compatibilidade abordam fluxos de trabalho específicos em detalhes.