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

## Ejemplo rápido

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

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

```php
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](https://greph.inline0.dev/es/docs/getting-started) y luego consulte [CLI](https://greph.inline0.dev/es/docs/cli) y [API](https://greph.inline0.dev/es/docs/api) para conocer las demás funciones. Las secciones [Modos](https://greph.inline0.dev/es/docs/modes/text), [Indexado](https://greph.inline0.dev/es/docs/indexed/text) y [Compatibilidad](https://greph.inline0.dev/es/docs/compatibility/rg) explican en detalle flujos de trabajo específicos.