# Introduction
Greph est un moteur de recherche et de refactorisation pour les arbres de code source, entièrement écrit en PHP. Il propose trois modes complémentaires :

- **Recherche de texte** avec une sortie compatible avec grep et une ergonomie de type ripgrep.
- **Recherche AST** avec des motifs structurels PHP et des métavariables.
- **Réécriture AST** pour le refactoring structurel qui préserve le formatage.

Il propose aussi des modes indexés préchauffés pour les charges de recherche de texte et AST, des politiques d’actualisation adaptées au cycle de vie, des ensembles d’index préchauffés gérés par manifeste, ainsi que des enveloppes de compatibilité `rg` / `sg` pour les environnements d’outils et d’agents.

## Pourquoi Greph existe

Les applications et agents PHP qui ont besoin d’une recherche de code rapide font généralement appel à des outils natifs (`grep`, `ripgrep`, `ast-grep`), au prix d’une moindre portabilité et d’une mise en place plus complexe. La recherche et la réécriture structurelles sont encore plus contraignantes : elles obligent généralement à quitter complètement le processus PHP.

Greph comble cette lacune. Votre code PHP peut effectuer des recherches textuelles, des correspondances structurelles et des réécritures de refactorisation avec uniquement la bibliothèque standard et `nikic/php-parser`. La sortie et les codes de sortie sont compatibles avec les outils de référence ; vos scripts et agents existants n’ont donc pas besoin de changer.

## Fonctionnalités

- Recherche de texte par chaîne fixe et expression régulière, avec modes de recherche de mots entiers, sans distinction de casse, de contexte, de décompte et de fichiers uniquement
- Recherche AST structurelle PHP avec `$VAR`, `$$$VARIADIC` et des métavariables répétées
- Réécriture AST qui préserve le formatage, avec modes simulation, interactif et écriture
- Index de texte préchauffés (trigrammes et index inversés d’identifiants) pour les charges répétées
- Index de faits AST préchauffé et recherche AST en cache pour les requêtes structurelles répétées
- Index préchauffés adaptés au cycle de vie : `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Recherche multi-index et par ensembles nommés dans les stockages préchauffés de texte, de faits AST et de caches AST
- Diagnostics du planificateur avec `--trace-plan` et indication de l’origine de l’index pour les recherches préchauffées
- Enveloppes de compatibilité ripgrep et ast-grep CLI reposant sur le même moteur
- Pool de processus de travail parallèles basé sur pcntl, avec repli sur un seul processus
- Parcoureur de fichiers qui respecte gitignore et `.grephignore`, avec détection des fichiers binaires

## Prérequis

- PHP 8.2 ou version ultérieure
- `ext-json`, `ext-ctype` et `ext-tokenizer`, activés dans presque toutes les compilations PHP
- `ext-zlib` pour le stockage de l’AST mis en cache (`greph-index ast-cache`)
- `nikic/php-parser` (l’unique dépendance Composer)

Les fonctionnalités de base de texte et d’AST s’exécutent en PHP pur. Les comparaisons de performances facultatives dépendent d’outils externes tels que `rg`, `grep` et `sg`, mais Greph peut fonctionner sans eux. Les analyses parallèles utilisent `ext-pcntl` lorsqu’il est disponible et repassent sans difficulté à un seul processus dans le cas contraire. Les hôtes qui interdisent `proc_open()` et `shell_exec()` sont décrits dans [Hôtes à processus restreints](https://greph.inline0.dev/fr/docs/advanced/process-restricted-hosts).

## Exemple rapide

Les exécutables `vendor/bin` nécessitent Greph 0.2.3 ou une version ultérieure lorsque Greph est installé comme dépendance de votre projet.

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

Commencez par [Premiers pas](https://greph.inline0.dev/fr/docs/getting-started), puis consultez [CLI](https://greph.inline0.dev/fr/docs/cli) et [API](https://greph.inline0.dev/fr/docs/api) pour découvrir le reste des fonctionnalités. Les sections [Modes](https://greph.inline0.dev/fr/docs/modes/text), [Indexation](https://greph.inline0.dev/fr/docs/indexed/text) et [Compatibilité](https://greph.inline0.dev/fr/docs/compatibility/rg) décrivent en détail des flux de travail spécifiques.