Greph
Motor puro de búsqueda de código PHP, búsqueda estructural y reescritura. Flujos de trabajo de grep, ripgrep y ast-grep en un único paquete Composer.
composer require greph/grephÚltima versión v0.2.3 MIT PHP 8.2+
# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src
# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' srcEn la práctica
Instala el paquete con Composer y luego busca y reescribe desde la línea de comandos o desde PHP.
Busca, encuentra coincidencias y previsualiza una reescritura
-F realiza una búsqueda de texto con cadenas literales, -p acepta un patrón con forma de PHP y metap variables como $CLASS, y -r añade una plantilla de reemplazo. --dry-run muestra los archivos reescritos sin guardarlos.
La fachada estática Greph ofrece las mismas operaciones al código PHP. Si se instala como dependencia, los comandos vendor/bin requieren la versión 0.2.3 o posterior.
# 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 srcuse 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(),
);PHP puro
La búsqueda y la reescritura se ejecutan en PHP 8.2+, sin los binarios grep, ripgrep ni ast-grep. Usa las extensiones json, ctype y tokenizer, además de zlib para el almacén AST en caché.
Búsqueda de texto
Búsqueda con cadenas literales y expresiones regulares, con modos de palabra completa, sin distinción entre mayúsculas y minúsculas, contexto, recuento y solo archivos. Salida compatible con grep.
Búsqueda AST
Búsqueda estructural de código fuente PHP con metap variables $VAR y $$$VARIADIC, capturas repetidas y salida JSON. PHP es el único lenguaje compatible.
Reescritura AST
Reescrituras estructurales con modos de simulación, interactivo y escritura. Solo cambia el código que coincide; los comentarios y el formato fuera de la coincidencia se mantienen.
Modos indexados
Crea una vez un índice de texto trigrama, un índice de datos AST o un almacén AST en caché y reutilízalo. En la prueba de rendimiento del proyecto, el índice de datos AST tardó 1.4 s en crearse y redujo new $CLASS() de 2.9 s a 11 ms; el índice trigrama tardó 12.3 s.
Envoltorios rg y sg
vendor/bin/rg y vendor/bin/sg aceptan los indicadores de búsqueda habituales de ripgrep y ast-grep con el mismo motor. No se admiten: búsqueda multilínea, --replace, --type-add ni --sort en rg; reglas YAML ni lenguajes distintos de PHP en sg.
PHP API
Greph::searchText(), searchAst() y rewriteAst() devuelven objetos de resultado tipados, para que el código PHP y los agentes invoquen el motor sin un subproceso.
Corpus de referencia
39 escenarios comparan las salidas de búsqueda de texto, AST y reescritura de greph con grep, ripgrep y ast-grep. Ejecútalos con composer test:oracle en un clon del repositorio; CI ejecuta las suites de pruebas unitarias y de integración.
Por qué Greph
Sin binarios nativos
La búsqueda y la reescritura se ejecutan dentro del proceso PHP. Los binarios rg, grep y sg solo se usan para las comparaciones opcionales de rendimiento.
Un motor para cada modo
La búsqueda de texto, la búsqueda estructural PHP y la reescritura están en un mismo paquete Composer. Los envoltorios rg y sg llaman al mismo motor que vendor/bin/greph.
Las reescrituras solo afectan las coincidencias
El reescritor inserta la plantilla generada en los rangos de bytes coincidentes. El código fuera de una coincidencia conserva su sangría, comentarios y líneas en blanco.
Índices precargados sin demonio
Los índices se guardan en disco y se reutilizan en ejecuciones posteriores. Un perfil del ciclo de vida determina si se deja intacto un índice obsoleto, se actualiza durante la búsqueda o se rechaza.
Comparación con
Greph mantiene la búsqueda y la reescritura en PHP. Estas herramientas resuelven problemas relacionados y algunas cosas que Greph no puede hacer.
| Herramienta | Ideal para | Diferencia con Greph |
|---|---|---|
| ripgrep | Ideal paraUna herramienta de búsqueda recursiva con expresiones regulares y compatibilidad nativa de primer nivel con Windows, macOS y Linux, además de descargas binarias para cada versión. Respeta las reglas de gitignore y omite de forma predeterminada los archivos ocultos y binarios. | Diferencia con GrephGreph se instala con Composer y se ejecuta en PHP. En su prueba de rendimiento de CI con el corpus WordPress, rg fue más rápido en todas las búsquedas de texto en frío; por ejemplo, tardó 81.62 ms frente a 458.82 ms en una búsqueda literal. Un índice Greph precargado respondió a una consulta de recuento en 10.90 ms, frente a 49.61 ms de rg. |
| ast-grep | Ideal paraUn CLI compilado para búsqueda estructural, análisis estático y reescritura, basado en tree-sitter. Incluye compatibilidad integrada con muchos lenguajes, entre ellos PHP, y archivos de reglas YAML para análisis estático y cambios de código. | Diferencia con GrephGreph solo procesa PHP y no lee reglas YAML. En una búsqueda en frío, sg fue más rápido para array($$$ITEMS) en la prueba de rendimiento de CI de Greph. El índice AST precargado de Greph respondió a new $CLASS() en 10.89 ms, frente a 4093.61 ms de sg. |
| Rector | Ideal paraActualiza y refactoriza código PHP mediante reglas y conjuntos de reglas, con cobertura de versiones PHP desde la 5.3 hasta la 8.5 y proyectos como Symfony, PHPUnit y Doctrine. | Diferencia con GrephGreph reescribe a partir de un patrón y una plantilla que tú defines. Su documentación lo descarta cuando un cambio depende de información de tipos que PHP-Parser no puede resolver a partir de un solo archivo, o cuando hay que añadir o eliminar imports entre archivos. |
| PHP CS Fixer | Ideal paraCorrige el código para que cumpla los estándares de programación, con conjuntos de reglas integrados como el estilo de programación PER de PHP-FIG. | Diferencia con GrephGreph no vuelve a formatear los archivos. Solo cambia el código que coincide con un patrón, y su documentación recomienda PHP CS Fixer cuando necesitas un formateador. |
Preguntas y respuestas
Respuestas breves de la documentación de Greph.
No. Greph ejecuta la búsqueda y la reescritura en PHP. Los binarios externos rg, grep y sg solo se usan para las comparaciones opcionales de rendimiento.
Solo PHP. Los patrones y archivos de código fuente se analizan con nikic/php-parser, y se rechaza cualquier otro valor de --lang por no ser compatible.
No en búsquedas en frío. En la prueba de rendimiento de CI del proyecto con el corpus WordPress, rg y grep fueron más rápidos en todas las búsquedas de texto en frío. Los índices precargados aceleran las consultas repetidas; por ejemplo, en un recuento indexado rg tardó 49.61 ms, frente a 10.90 ms.
Greph se ejecuta en un solo proceso. Sin pcntl_fork, el grupo de trabajadores procesa cada bloque dentro del mismo proceso, con el mismo resultado que -j 1, y no genera ningún error.
Fuera de las coincidencias, no. El código fuera de los rangos de bytes coincidentes conserva los espacios en blanco, los comentarios y el formato. El código coincidente se vuelve a generar a partir de la plantilla, por lo que se normalizan sus saltos de línea y se puede perder un comentario que contenga. Ejecuta con --dry-run primero para mostrar los archivos reescritos sin guardarlos.
De forma predeterminada, en .greph-index, .greph-ast-index y .greph-ast-cache, en la raíz indexada. Pasa --index-dir a cualquier subcomando greph-index para usar otra ubicación.
Consulta la documentación de Greph para ver la referencia de CLI, la PHP API, los modos indexados y los envoltorios rg y sg.