# Introdução
Greph é um mecanismo puro de pesquisa e refatoração PHP para árvores de código-fonte. Ele abrange três modos relacionados:

- **Pesquisa de texto** com saída compatível com grep e praticidade no estilo de ripgrep.
- **Pesquisa de AST** com padrões estruturais PHP e metavariáveis.
- **Reescrita de AST** com refatoração estrutural que preserva a formatação.

Também inclui modos indexados aquecidos para cargas de trabalho de texto e AST, políticas de atualização atentas ao ciclo de vida, conjuntos de índices aquecidos respaldados por manifestos e wrappers de compatibilidade `rg` / `sg` para ambientes de ferramentas e agentes.

## Por que Greph existe

Aplicações e agentes PHP que precisam de pesquisa rápida de código geralmente recorrem a ferramentas nativas (`grep`, `ripgrep`, `ast-grep`), abrindo mão da portabilidade e adicionando dificuldades de implantação. A pesquisa e a reescrita estruturais são ainda mais difíceis: normalmente exigem sair completamente do processo PHP.

Greph elimina essa lacuna. Seu código PHP pode executar pesquisas de texto, correspondências estruturais e reescritas de refatoração usando apenas a biblioteca padrão e `nikic/php-parser`. A saída e os códigos de saída são compatíveis com as ferramentas canônicas, então os scripts e agentes existentes não precisam mudar.

## O que ele faz

- Pesquisa de texto por strings literais e expressões regulares, com modos para palavras inteiras, diferenciação entre maiúsculas e minúsculas, contexto, contagem e somente arquivos
- Pesquisa estrutural de AST PHP com padrões `$VAR`, `$$$VARIADIC` e metavariáveis repetidas
- Reescrita de AST que preserva a formatação, com modos de simulação, interativo e gravação
- Índices de texto aquecidos (trigramas + listas de identificadores) para cargas de trabalho repetidas
- Índice de fatos de AST aquecido e pesquisa de AST em cache para consultas estruturais repetidas
- Índices aquecidos atentos ao ciclo de vida: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Pesquisa em vários índices e conjuntos nomeados nos armazenamentos aquecidos de texto, fatos de AST e cache de AST
- Diagnósticos do planejador com `--trace-plan` e identificação da origem do índice nas pesquisas aquecidas
- Wrappers de compatibilidade ripgrep e ast-grep CLI respaldados pelo mesmo mecanismo
- Conjunto de processos de trabalho paralelos baseado em pcntl, com alternativa de processo único
- Percursor de arquivos atento a gitignore e `.grephignore`, com detecção de arquivos binários

## O que é necessário

- PHP 8.2 ou posterior
- `ext-json`, `ext-ctype` e `ext-tokenizer`, habilitados em quase todas as compilações de PHP
- `ext-zlib` para o armazenamento de AST em cache (`greph-index ast-cache`)
- `nikic/php-parser` (a única dependência de Composer)

Os recursos essenciais de texto e AST funcionam em PHP puro. As comparações opcionais de benchmark dependem de ferramentas externas como `rg`, `grep` e `sg`, mas o próprio Greph não precisa delas para funcionar. As varreduras paralelas usam `ext-pcntl` quando disponível e recorrem normalmente à execução em processo único quando não está. Hosts que proíbem `proc_open()` e `shell_exec()` são abordados em [Hosts com restrições a processos](https://greph.inline0.dev/pt/docs/advanced/process-restricted-hosts).

## Exemplo rápido

Os executáveis `vendor/bin` precisam de Greph 0.2.3 ou posterior quando Greph é instalado como dependência do seu projeto.

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

Comece por [Primeiros passos](https://greph.inline0.dev/pt/docs/getting-started) e depois consulte [CLI](https://greph.inline0.dev/pt/docs/cli) e [API](https://greph.inline0.dev/pt/docs/api) para conhecer os demais recursos. As seções [Modos](https://greph.inline0.dev/pt/docs/modes/text), [Indexação](https://greph.inline0.dev/pt/docs/indexed/text) e [Compatibilidade](https://greph.inline0.dev/pt/docs/compatibility/rg) abordam fluxos de trabalho específicos em detalhes.