Saltar al contenido

Primeros pasos

Ver como Markdown Editar en GitHub Documentación de d105217

Instalación

Instale Greph mediante Composer:

Shell
composer require greph/greph

Esto instala la biblioteca y cuatro ejecutables en vendor/bin/:

  • greph: búsqueda de texto nativa, búsqueda AST y reescritura AST
  • greph-index: índice de texto precargado, índice de hechos AST y búsqueda AST en caché
  • rg: envoltorio de compatibilidad al estilo de ripgrep
  • sg: envoltorio de compatibilidad al estilo de ast-grep

Estos ejecutables funcionan desde el directorio vendor/bin/ de su proyecto, ya que Greph 0.2.3. Las versiones anteriores solo encontraban el cargador automático de Composer dentro de un clon del repositorio Greph, así que use al menos esa versión:

Shell
composer require greph/greph:^0.2.3

Requisitos

  • PHP 8.2+ para clases de solo lectura, enumeraciones, sintaxis de funciones invocables de primera clase y promoción de constructores
  • ext-json para la salida JSON y los datos del índice almacenados en disco
  • ext-ctype para el análisis de patrones y opciones
  • ext-tokenizer para PHP-Parser y los pre filtros del AST
  • ext-zlib para el almacén de AST en caché (greph-index ast-cache)
  • nikic/php-parser (se instala automáticamente como dependencia de Composer)

ext-json, ext-ctype y ext-tokenizer están habilitados en casi todas las compilaciones de PHP. composer.json declara solo ext-json por ahora (#5), así que Composer no avisa si falta alguno de los otros.

Opcional:

  • ext-pcntl para análisis paralelos. Greph pasa sin problemas a la ejecución en un solo proceso si no está disponible.
  • Binarios externos de rg, grep y sg para comparar benchmarks. Nunca son necesarios en tiempo de ejecución.

Las búsquedas, reescrituras e indexaciones nunca invocan proc_open() ni shell_exec(); solo los análisis paralelos crean procesos secundarios, y pasan a un único proceso si no está disponible pcntl_fork(). Consulte Hosts con restricciones de procesos para los hosts que deshabilitan proc_open(), shell_exec() o pcntl_fork().

Su primera búsqueda de texto

El modo predeterminado de Greph es la búsqueda de texto compatible con grep:

Shell
vendor/bin/greph -F "function" src

La salida usa el formato canónico file:line:content que esperan grep, ripgrep y la mayoría de las integraciones con editores.

Text
src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(

Añada -i para distinguir mayúsculas y minúsculas, -w para coincidencias de palabras completas, -c para recuentos, -l solo para rutas de archivos, -C 2 para dos líneas de contexto, etc. La lista completa está en la referencia de CLI.

Pase -p y un patrón con forma de PHP para cambiar a la búsqueda estructural:

Shell
vendor/bin/greph -p 'new $CLASS()' src

$CLASS es una metavariable que captura cualquier nombre de clase. El patrón new $CLASS() coincide con cada expresión new sin argumentos, independientemente de la clase, el formato o los comentarios. Use new $CLASS($$$ARGS) para coincidir con llamadas con cualquier número de argumentos.

Cada coincidencia del AST se muestra como el archivo, la línea inicial y el código coincidente:

Text
src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()

Otros patrones útiles:

Shell
# 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)' src

Consulte Modos / Búsqueda de AST para ver la sintaxis completa de los patrones.

Su primera reescritura

Añada -r para convertir la búsqueda del AST en una reescritura:

Shell
# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Las reescrituras conservan el formato fuera de la coincidencia: solo se reemplaza el nodo coincidente, y los espacios, la sangría y los comentarios que lo rodean se mantienen intactos. El nodo coincidente se genera de nuevo a partir de la plantilla, por lo que su propio diseño se normaliza y puede perderse un comentario que contenga. Consulte Modos / Reescritura para obtener más información.

PHP API

La interfaz estática Greph\Greph expone las mismas operaciones que CLI:

PHP
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

La interfaz completa se describe en API.

Las cargas de trabajo repetidas se benefician de índices precargados. Créelos una vez y luego consulte tantas veces como necesite:

Shell
# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src

De forma predeterminada, los índices se guardan en .greph-index, .greph-ast-index y .greph-ast-cache en la raíz del proyecto.

Para árboles que cambian con frecuencia, elija un perfil de ciclo de vida en lugar de tratar todos los índices precargados de la misma manera:

Shell
vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh

El patrón habitual es:

  • mantener una base estable como static
  • mantener las capas superpuestas que cambian con frecuencia como opportunistic-refresh
  • inspeccionar el comportamiento obsoleto con stats --dry-refresh

Puede buscar en varios índices precargados con un solo comando:

Shell
vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin

Conjuntos de índices con nombre

Si repite esta operación, defina la estructura en .greph-index-set.json y use los subcomandos del conjunto en vez de repetir las opciones:

Shell
vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Traza del planificador

Para ver cómo la búsqueda precargada reduce el conjunto de candidatos, añada --trace-plan:

Shell
vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .

Consulte Indexado / Texto y Indexado / AST para conocer todo el flujo de trabajo con índices precargados.

Adaptadores de compatibilidad

Si tiene herramientas o agentes que ya usan ripgrep o ast-grep, incorpore los adaptadores:

Shell
vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Ambos adaptadores reutilizan el mismo motor y se han verificado mediante pruebas con los binarios originales. La funcionalidad verificada se documenta en Compatibilidad / rg y Compatibilidad / sg y se reproduce en la matriz de funcionalidades generada.

Configuración

Greph reconoce dos convenciones almacenadas en disco:

  • .gitignore: se respeta de forma predeterminada. Pase --no-ignore para deshabilitarlo.
  • .grephignore: usa la misma sintaxis que .gitignore y se aplica encima. Es útil para exclusiones específicas de herramientas que no quiera incluir en el control de versiones.

Los directorios de índice predeterminados son .greph-index, .greph-ast-index y .greph-ast-cache en la raíz elegida. Anúlelos con --index-dir en cualquier subcomando greph-index, o use .greph-index-set.json para diseños repetibles con varios índices.