# Primeiros passos

## Instalação

Instale Greph por meio de Composer:

```bash
composer require greph/greph
```

Isso instala a biblioteca e quatro executáveis em `vendor/bin/`:

- `greph`: pesquisa nativa de texto, pesquisa AST e reescrita AST
- `greph-index`: índice de texto aquecido, índice de fatos AST e pesquisa AST em cache
- `rg`: wrapper de compatibilidade no estilo ripgrep
- `sg`: wrapper de compatibilidade no estilo ast-grep

Esses executáveis funcionam no diretório `vendor/bin/` do seu projeto, pois Greph 0.2.3. Versões anteriores só encontravam o autoloader Composer dentro de um clone do repositório Greph; por isso, use ao menos essa versão:

```bash
composer require greph/greph:^0.2.3
```

## Requisitos

- **PHP 8.2+** para classes somente leitura, enums, sintaxe de callable de primeira classe e promoção de construtor
- **ext-json** para a saída JSON e payloads de índice em disco
- **ext-ctype** para análise de padrões e opções
- **ext-tokenizer** para PHP-Parser e os pré-filtros da AST
- **ext-zlib** para o armazenamento de AST em cache (`greph-index ast-cache`)
- **nikic/php-parser** (instalado automaticamente como dependência de Composer)

`ext-json`, `ext-ctype` e `ext-tokenizer` estão habilitados em quase todas as compilações de PHP. `composer.json` declara apenas `ext-json` no momento ([#5](https://github.com/inline0/greph/issues/5)), então Composer não emite avisos quando algum dos outros está ausente.

Opcional:

- **ext-pcntl** para varreduras paralelas. Greph recorre normalmente à execução em processo único quando ele está ausente.
- Binários externos de `rg`, `grep` e `sg` para comparações de benchmark. Eles nunca são necessários em tempo de execução.

A pesquisa, a reescrita e a indexação nunca chamam `proc_open()` ou `shell_exec()`; somente as varreduras paralelas criam processos, e recorrem a um único processo sem `pcntl_fork()`. Consulte [Hosts com restrições a processos](https://greph.inline0.dev/pt/docs/advanced/process-restricted-hosts) para saber sobre hosts que desabilitam `proc_open()`, `shell_exec()` ou `pcntl_fork()`.

## Sua primeira pesquisa de texto

O modo padrão de Greph é a pesquisa de texto compatível com grep:

```bash
vendor/bin/greph -F "function" src
```

A saída usa o formato canônico de `file:line:content` que grep, ripgrep e a maioria das integrações com editores esperam.

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

Adicione `-i` para ignorar maiúsculas e minúsculas, `-w` para corresponder a palavras inteiras, `-c` para contagens, `-l` apenas para caminhos de arquivos, `-C 2` para duas linhas de contexto e assim por diante. A lista completa está na referência de [opçõesCLI](https://greph.inline0.dev/pt/docs/cli).

## Sua primeira pesquisa de AST

Passe `-p` e um padrão no formato de PHP para mudar para a pesquisa estrutural:

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

`$CLASS` é uma metavariável que captura qualquer nome de classe. O padrão `new $CLASS()` corresponde a todas as expressões `new` sem argumentos, independentemente da classe, formatação ou dos comentários. Use `new $CLASS($$$ARGS)` para corresponder a chamadas com quaisquer argumentos.

Cada correspondência de AST é exibida como arquivo, linha inicial e código correspondente:

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

Outros padrões úteis:

```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 / Pesquisa de AST](https://greph.inline0.dev/pt/docs/modes/ast) para ver a sintaxe completa dos padrões.

## Sua primeira reescrita

Adicione `-r` para transformar a pesquisa de AST em uma reescrita:

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

As reescritas preservam a formatação fora da correspondência: apenas o nó correspondente é substituído, enquanto os espaços em branco, a indentação e os comentários ao redor permanecem intactos. O próprio nó correspondente é gerado novamente a partir do modelo, então sua disposição é normalizada e um comentário dentro dele pode se perder. Consulte [Modos / Reescrita](https://greph.inline0.dev/pt/docs/modes/rewrite) para obter detalhes.

## PHP API

A fachada estática `Greph\Greph` expõe as mesmas operações 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";
}
```

A interface completa está descrita em [API](https://greph.inline0.dev/pt/docs/api).

## Pesquisa indexada

Cargas de trabalho repetidas se beneficiam de índices aquecidos. Crie o índice uma vez e faça consultas várias vezes:

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

Por padrão, os índices ficam em `.greph-index`, `.greph-ast-index` e `.greph-ast-cache` na raiz do projeto.

Para árvores que mudam ativamente, escolha um perfil de ciclo de vida em vez de tratar todos os índices aquecidos da mesma forma:

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

O padrão mais comum é:

- manter uma base estável como `static`
- manter sobreposições que mudam ativamente como `opportunistic-refresh`
- inspecionar comportamentos obsoletos com `stats --dry-refresh`

### Pesquisa aquecida em vários índices

Você pode pesquisar em vários índices aquecidos com um único 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 nomeados

Se você fizer isso repetidamente, coloque a configuração em `.greph-index-set.json` e use os subcomandos de conjunto em vez de repetir as opções:

```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)' .
```

### Rastreamento do planejador

Para ver como a pesquisa aquecida está reduzindo o conjunto de candidatos, adicione `--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/pt/docs/indexed/text) e [Indexado / AST](https://greph.inline0.dev/pt/docs/indexed/ast) para ver o fluxo completo de trabalho com índices aquecidos.

## Wrappers de compatibilidade

Se você tem ferramentas ou agentes que já usam ripgrep ou ast-grep, adicione os wrappers:

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

Ambos os wrappers reutilizam o mesmo mecanismo e são verificados por sondagem em relação aos binários upstream. A interface verificada está documentada em [Compatibilidade / rg](https://greph.inline0.dev/pt/docs/compatibility/rg) e [Compatibilidade / sg](https://greph.inline0.dev/pt/docs/compatibility/sg), e reproduzida na [matriz de funcionalidades](https://greph.inline0.dev/pt/docs/advanced/feature-matrix) gerada.

## Configuração

Greph reconhece duas convenções em disco:

- `.gitignore`: respeitado por padrão. Passe `--no-ignore` para desabilitar.
- `.grephignore`: mesma sintaxe de `.gitignore`, aplicada por cima. Útil para exclusões específicas de ferramentas que você não quer manter no controle de versão.

Os diretórios de índice padrão são `.greph-index`, `.greph-ast-index` e `.greph-ast-cache` na raiz escolhida. Substitua-os com `--index-dir` em qualquer subcomando `greph-index` ou use `.greph-index-set.json` para configurações repetíveis com vários índices.