Introducción

Greph es un motor de búsqueda y refactorización para árboles de código fuente que usa solo PHP. Ofrece tres modos relacionados:

• Búsqueda de texto con salida compatible con grep y una experiencia de uso al estilo de ripgrep.
• Búsqueda de AST con patrones estructurales PHP y metavariables.
• Reescritura de AST para refactorizar estructuras conservando el formato.

También incluye modos indexados precargados para cargas de trabajo de texto y AST, políticas de actualización según el ciclo de vida, conjuntos de índices precargados respaldados por manifiestos y adaptadores de compatibilidad de rg / sg para herramientas y entornos de agentes.

Por qué existe Greph

Las aplicaciones PHP y los agentes que necesitan buscar código con rapidez suelen recurrir a herramientas nativas (grep, ripgrep, ast-grep), lo que reduce la portabilidad y complica la implementación. La búsqueda y reescritura estructurales presentan aún más dificultades: normalmente obligan a salir por completo del proceso PHP.

Greph elimina esa brecha. Su código PHP puede realizar búsquedas de texto, coincidencias estructurales y reescrituras de refactorización usando solo la biblioteca estándar y nikic/php-parser. La salida y los códigos de salida son compatibles con las herramientas canónicas, así que no es necesario cambiar los scripts ni los agentes existentes.

Qué hace

• Búsqueda de texto con cadenas literales y expresiones regulares, con opciones para palabras completas, distinción entre mayúsculas y minúsculas, contexto, recuentos y solo archivos
• Búsqueda estructural de AST PHP con $VAR, $$$VARIADIC y metavariables repetidas
• Reescritura de AST que conserva el formato, con modos de simulación, interactivo y de escritura
• Índices de texto precargados (publicaciones de trigramas e identificadores) para cargas de trabajo repetidas
• Índice de datos de AST precargado y búsqueda de AST en caché para consultas estructurales repetidas
• Índices precargados según el ciclo de vida: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Búsqueda en varios índices y conjuntos con nombre en almacenes precargados de texto, datos de AST y caché de AST
• Diagnóstico del planificador con --trace-plan y etiquetas de origen del índice para búsquedas precargadas
• Adaptadores de compatibilidad ripgrep y ast-grep CLI respaldados por el mismo motor
• Grupo de procesos de trabajo paralelos basado en pcntl, con alternativa de un solo proceso
• Recorrido de archivos que respeta gitignore y .grephignore y detecta archivos binarios

Requisitos

• PHP 8.2 o posterior
• ext-json, ext-ctype y ext-tokenizer, habilitados en casi todas las compilaciones de PHP
• ext-zlib para el almacén de AST en caché (greph-index ast-cache)
• nikic/php-parser (la única dependencia de Composer)

Las funciones principales de texto y AST se ejecutan con PHP. Las comparaciones opcionales de benchmarks dependen de herramientas externas como rg, grep y sg, pero Greph funciona sin ellas. Los análisis paralelos usan ext-pcntl cuando está disponible y, de lo contrario, pasan sin problemas a ejecutarse en un solo proceso. Los hosts que prohíben proc_open() y shell_exec() se describen en Hosts con restricciones de procesos.

Ejemplo rápido

Los ejecutables vendor/bin necesitan Greph 0.2.3 o posterior cuando Greph se instala como dependencia del proyecto.

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

Empiece por Primeros pasos y luego consulte CLI y API para conocer las demás funciones. Las secciones Modos, Indexado y Compatibilidad explican en detalle flujos de trabajo específicos.