# Primeros pasos

## Instalación

Instale Greph mediante Composer:

```bash
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:

```bash
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](https://github.com/inline0/greph/issues/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](https://greph.inline0.dev/es/docs/advanced/process-restricted-hosts) 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:

```bash
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](https://greph.inline0.dev/es/docs/cli).

## Su primera búsqueda de AST

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

```bash
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:

```bash
# 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](https://greph.inline0.dev/es/docs/modes/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:

```bash
# 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](https://greph.inline0.dev/es/docs/modes/rewrite) 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](https://greph.inline0.dev/es/docs/api).

## Búsqueda indexada

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

```bash
# 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:

```bash
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`

### Búsqueda precargada en varios índices

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

```bash
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:

```bash
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`:

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

Consulte [Indexado / Texto](https://greph.inline0.dev/es/docs/indexed/text) y [Indexado / AST](https://greph.inline0.dev/es/docs/indexed/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:

```bash
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](https://greph.inline0.dev/es/docs/compatibility/rg) y [Compatibilidad / sg](https://greph.inline0.dev/es/docs/compatibility/sg) y se reproduce en la [matriz de funcionalidades](https://greph.inline0.dev/es/docs/advanced/feature-matrix) 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.