# Premiers pas

## Installation

Installez Greph avec Composer :

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

Cela installe la bibliothèque et quatre exécutables dans `vendor/bin/` :

- `greph` : recherche textuelle native, recherche AST et réécriture AST
- `greph-index` : index textuel préchauffé, index de faits AST et recherche AST mise en cache
- `rg` : enveloppe de compatibilité de type ripgrep
- `sg` : enveloppe de compatibilité de type ast-grep

Ces exécutables fonctionnent depuis le répertoire `vendor/bin/` de votre projet, puisque Greph 0.2.3. Les versions antérieures ne trouvaient l’autoloader Composer qu’à l’intérieur d’un clone du dépôt Greph ; utilisez donc au moins cette version :

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

## Prérequis

- **PHP 8.2+** pour les classes en lecture seule, les énumérations, la syntaxe des fonctions appelables de première classe et la promotion des propriétés du constructeur
- **ext-json** pour la sortie JSON et les données d’index stockées sur disque
- **ext-ctype** pour l’analyse des motifs et des options
- **ext-tokenizer** pour PHP-Parser et les pré-filtres de l’AST
- **ext-zlib** pour le stockage de l’AST mis en cache (`greph-index ast-cache`)
- **nikic/php-parser** (installé automatiquement comme dépendance Composer)

`ext-json`, `ext-ctype` et `ext-tokenizer` sont activés dans presque toutes les compilations PHP. Pour le moment, `composer.json` ne déclare que `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), donc Composer n’émet pas d’avertissement si l’un des autres manque.

Facultatif :

- **ext-pcntl** pour les analyses parallèles. Greph passe sans difficulté à une exécution sur un seul processus lorsqu’il est absent.
- Binaires `rg`, `grep` et `sg` externes pour les comparaisons de performances. Ils ne sont jamais requis à l’exécution.

La recherche, la réécriture et l’indexation n’appellent jamais `proc_open()` ni `shell_exec()` ; seules les analyses parallèles créent des processus fils, et elles repassent à un seul processus en l’absence de `pcntl_fork()`. Consultez [Hôtes à processus restreints](https://greph.inline0.dev/fr/docs/advanced/process-restricted-hosts) pour les hôtes qui désactivent `proc_open()`, `shell_exec()` ou `pcntl_fork()`.

## Votre première recherche de texte

Le mode par défaut de Greph est la recherche de texte compatible avec grep :

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

La sortie utilise le format canonique `file:line:content` attendu par grep, ripgrep et la plupart des intégrations d’éditeurs.

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

Ajoutez `-i` pour ignorer la casse, `-w` pour rechercher des mots entiers, `-c` pour obtenir des décomptes, `-l` pour n’afficher que les chemins des fichiers, `-C 2` pour deux lignes de contexte, et ainsi de suite. La liste complète figure dans la [référence CLI](https://greph.inline0.dev/fr/docs/cli).

## Votre première recherche AST

Passez `-p` et un motif de la forme PHP pour activer la recherche structurelle :

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

`$CLASS` est une métavariable qui capture n’importe quel nom de classe. Le motif `new $CLASS()` correspond à chaque expression `new` sans argument, quels que soient la classe, le formatage ou les commentaires. Utilisez `new $CLASS($$$ARGS)` pour trouver les appels avec n’importe quels arguments.

Chaque correspondance AST affiche le fichier, la ligne de début et le code correspondant :

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

Autres motifs utiles :

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

Consultez [Modes / Recherche AST](https://greph.inline0.dev/fr/docs/modes/ast) pour connaître toute la syntaxe des motifs.

## Votre première réécriture

Ajoutez `-r` pour transformer la recherche AST en réécriture :

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

Les réécritures préservent le format en dehors de la correspondance : seul le nœud correspondant est remplacé, et les espaces, l’indentation et les commentaires environnants restent intacts. Le nœud correspondant lui-même est recréé à partir du modèle ; sa mise en forme est donc normalisée et un commentaire qu’il contient peut être perdu. Consultez [Modes / Réécriture](https://greph.inline0.dev/fr/docs/modes/rewrite) pour en savoir plus.

## PHP API

La façade statique `Greph\Greph` expose les mêmes opérations 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 référence complète est présentée dans [API](https://greph.inline0.dev/fr/docs/api).

## Recherche indexée

Les charges de travail répétées bénéficient d’index préchauffés. Créez l’index une fois, puis lancez plusieurs requêtes :

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

Par défaut, les index se trouvent dans `.greph-index`, `.greph-ast-index` et `.greph-ast-cache` à la racine du projet.

Pour les arborescences qui changent activement, choisissez un profil de cycle de vie au lieu de traiter tous les index préchauffés de la même façon :

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

Le schéma courant est le suivant :

- conserver une base stable comme `static`
- conserver les superpositions qui changent activement comme `opportunistic-refresh`
- examiner le comportement des données obsolètes avec `stats --dry-refresh`

### Recherche préchauffée sur plusieurs index

Vous pouvez rechercher dans plusieurs index préchauffés avec une seule commande :

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

### Ensembles d’index nommés

Si vous répétez cette opération, définissez la configuration dans `.greph-index-set.json` et utilisez les sous-commandes d’ensemble au lieu de répéter les options :

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

### Trace du planificateur

Pour voir comment la recherche préchauffée réduit le nombre de candidats, ajoutez `--trace-plan` :

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

Consultez [Indexation / Texte](https://greph.inline0.dev/fr/docs/indexed/text) et [Indexation / AST](https://greph.inline0.dev/fr/docs/indexed/ast) pour découvrir l’ensemble du flux de travail avec préchauffage.

## Enveloppes de compatibilité

Si vos outils ou agents utilisent déjà ripgrep ou ast-grep, intégrez les enveloppes :

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

Les deux enveloppes réutilisent le même moteur et leur compatibilité a été vérifiée par sondage par rapport aux binaires amont. Les fonctionnalités vérifiées sont documentées dans [Compatibilité / rg](https://greph.inline0.dev/fr/docs/compatibility/rg) et [Compatibilité / sg](https://greph.inline0.dev/fr/docs/compatibility/sg), et reprises dans la [matrice des fonctionnalités générée](https://greph.inline0.dev/fr/docs/advanced/feature-matrix).

## Configuration

Greph prend en charge deux conventions stockées sur disque :

- `.gitignore` : pris en compte par défaut. Passez `--no-ignore` pour le désactiver.
- `.grephignore` : même syntaxe que `.gitignore`, appliqué par-dessus. Pratique pour les exclusions propres à un outil que vous ne souhaitez pas versionner.

Par défaut, les répertoires d’index sont `.greph-index`, `.greph-ast-index` et `.greph-ast-cache` à la racine choisie. Remplacez-les avec `--index-dir` pour toute sous-commande `greph-index`, ou utilisez `.greph-index-set.json` pour des configurations reproductibles à plusieurs index.