# API

`Rudel\Rudel` est une façade statique. Chaque méthode présentée sur cette page est une méthode statique publique de cette classe.

```php
use Rudel\Rudel;

if ( Rudel::is_sandbox() ) {
    error_log( 'Running in sandbox ' . Rudel::id() );
}
```

Les méthodes de cycle de vie qui clonent ou suppriment des tables (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) nécessitent une requête WordPress active avec `$wpdb`. Elles lèvent une `RuntimeException` lorsqu’elles sont appelées après `Rudel::init()` en dehors de WordPress. Voir [Utilisation autonome](https://rudel.inline0.dev/fr/docs/features/standalone-use).

## Contexte d’exécution

Ces méthodes décrivent la requête actuelle. En dehors d’un environnement isolé, elles renvoient `false` ou `null`.

| Méthode | Valeur renvoyée |
|--------|---------|
| `is_sandbox(): bool` | `true` si la requête actuelle s’exécute dans un environnement isolé |
| `id(): ?string` | l’identifiant de l’environnement isolé actuel |
| `path(): ?string` | le répertoire de l’environnement isolé actuel |
| `engine(): ?string` | `overlay` dans un environnement isolé |
| `table_prefix(): ?string` | le préfixe des tables de l’environnement isolé, par exemple `wp_b65338d_` |
| `url(): ?string` | le URL de l’environnement isolé ; les environnements isolés en surcouche partagent le URL hôte |
| `exit_url(): string` | le URL hôte |
| `is_email_disabled(): bool` | `true` lorsque l’envoi de courrier sortant est bloqué pour la requête |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | la version installée de Rudel |
| `cli_command(): string` | la commande racine WP-CLI, `rudel` sauf si `RUDEL_CLI_COMMAND` est défini |

### `Rudel::context(): array`

Renvoie tous les éléments ci-dessus dans un tableau :

```php
[
    'is_sandbox'     => true,
    'id'             => 'alpha-3be7',
    'path'           => '/var/www/html/wp-content/rudel-environments/alpha-3be7',
    'engine'         => 'overlay',
    'table_prefix'   => 'wp_b65338d_',
    'url'            => 'http://localhost/',
    'exit_url'       => 'http://localhost/',
    'email_disabled' => true,
    'log_path'       => '/var/www/html/wp-content/rudel-environments/alpha-3be7/debug.log',
    'version'        => '0.10.0',
    'cli_command'    => 'rudel',
]
```

### `Rudel::status(): array`

Renvoie le même résumé d’exécution que `wp rudel status` sous forme de tableau : état de l’initialisation, environnement isolé actuel, répertoire et nombre d’environnements isolés, valeurs `rudel_config` et présence ou non d’une automatisation planifiée.

## Enregistrements des environnements isolés

Les environnements isolés sont renvoyés sous forme d’objets `Rudel\Environment`. Parmi les propriétés utiles en lecture seule figurent `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` et `clone_source`. Les méthodes comprennent `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` et `to_array()`.

### `Rudel::all(): array`

Renvoie tous les environnements isolés sous forme d’un tableau d’objets `Environment`. Aucun filtre n’est appliqué.

```php
foreach ( Rudel::all() as $sandbox ) {
    echo $sandbox->id . ' ' . $sandbox->status . "\n";
}
```

### `Rudel::get( string $id ): ?Environment`

Charge un environnement isolé par son ID, ou renvoie `null`.

```php
$sandbox = Rudel::get( 'alpha-3be7' );
```

### `Rudel::environments_dir(): string`

Renvoie le répertoire contenant les répertoires des environnements isolés.

## Cycle de vie

### `Rudel::create( string $name, array $options = [] ): Environment`

Crée un environnement isolé et le renvoie. L’ID est généré à partir du nom et de quatre caractères hexadécimaux.

```php
$sandbox = Rudel::create( 'alpha', [
    'theme'    => 'twentytwentyfour',
    'owner'    => 'dennis',
    'labels'   => [ 'qa', 'agent' ],
    'ttl_days' => 7,
] );
```

Options :

| Clé | Signification |
|-----|---------|
| `theme` | identifiant de thème à copier dans l’environnement isolé ; par défaut, le thème actif de l’hôte |
| `clone_from` | ID d’un environnement isolé existant à cloner à la place de l’hôte |
| `owner`, `purpose` | métadonnées en texte libre |
| `labels` | tableau ou chaîne séparée par des virgules |
| `protected` | `true` pour exclure l’environnement isolé du nettoyage |
| `ttl_days` | expiration calculée à partir de l’heure de création |
| `expires_at` | horodatage d’expiration explicite |
| `template` | libellé enregistré dans l’enregistrement ; ne charge pas de modèle enregistré |
| `site_options` | noms d’options et valeurs scalaires écrits dans la table des options de l’environnement isolé |
| `skip_limits` | `true` pour contourner `max_sandboxes` et `max_disk_mb` |

### `Rudel::create_from_git( string $remote_url, array $options = [] ): array`

Crée un environnement isolé, puis y clone `$remote_url`. Accepte les options `create()` ainsi que `name` (nom du dépôt par défaut) et `type` (`theme` ou `plugin`). Renvoie `[ 'environment' => Environment, 'git' => [...] ]`. Un échec du clonage n’annule pas la création de l’environnement isolé ; l’erreur est renvoyée dans `git.error`. Voir [Git](https://rudel.inline0.dev/fr/docs/features/git).

### `Rudel::update( string $id, array $changes ): Environment`

Met à jour les métadonnées du cycle de vie et renvoie l’environnement isolé actualisé. Les clés acceptées comprennent `owner`, `labels`, `purpose`, `protected`, `ttl_days` (à partir de l’heure actuelle), `expires_at`, `clear_expiry`, `name` et `site_options`.

```php
Rudel::update( 'alpha-3be7', [ 'protected' => true, 'ttl_days' => 3 ] );
```

### `Rudel::destroy( string $id ): bool`

Supprime les tables de l’environnement isolé, son répertoire et les worktrees associés, puis efface son enregistrement. Renvoie `false` si l’ID n’existe pas. La protection n’est pas vérifiée : les environnements isolés protégés sont également détruits.

### `Rudel::cleanup( array $options = [] ): array`

Applique les règles d’expiration, d’ancienneté et d’inactivité. Options : `dry_run` (bool), `max_age_days` et `max_idle_days` (remplacent `rudel_config` si la valeur est non nulle). Renvoie `removed`, `skipped`, `errors` et `reasons` (ID vers `expired`, `age`, `idle` ou `protected`). Voir [Nettoyage](https://rudel.inline0.dev/fr/docs/features/cleanup).

### `Rudel::cleanup_merged( array $options = [] ): array`

Supprime les environnements isolés dont les branches de worktree Git associées ont été fusionnées dans la branche par défaut du dépôt. Option : `dry_run`.

### `Rudel::touch_current_environment(): void`

Enregistre l’activité (`last_used_at`) de l’environnement isolé actuel. Rudel l’appelle pour chaque requête dans un environnement isolé.

## Journaux

### `Rudel::read_log( string $id, int $lines = 50 ): array`

Renvoie les dernières lignes du `debug.log` de l’environnement isolé sous forme de `path`, `exists`, `empty`, `total_lines` et `lines`.

### `Rudel::clear_log( string $id ): array`

Vide le `debug.log` de l’environnement isolé et renvoie `path`, `existed` et `cleared`.

## Instantanés

### `Rudel::snapshot( string $id, string $name ): array`

Crée un instantané et renvoie ses métadonnées (`name`, `created_at`, `sandbox_id`).

### `Rudel::restore( string $id, string $name ): void`

Restaure un instantané. Avec le paramètre `auto_snapshot_before_restore` par défaut, Rudel enregistre d’abord un instantané `pre-restore-...`.

### `Rudel::snapshots( string $id ): array`

Répertorie les métadonnées des instantanés, du plus récent au plus ancien. Voir [Instantanés](https://rudel.inline0.dev/fr/docs/features/snapshots).

## Modèles

- `Rudel::save_template( string $id, string $name, string $description = '' ): array`
- `Rudel::templates(): array`
- `Rudel::delete_template( string $name ): bool`

Les modèles enregistrés sont uniquement des copies de fichiers. Aucune API ni commande ne crée d’environnement isolé à partir d’un modèle. Voir [Modèles](https://rudel.inline0.dev/fr/docs/features/templates).

## Git

### `Rudel::push( string $id, string $remote_url = '', string $message = 'Update from Rudel', string $subdir = '' ): ?string`

Valide et envoie un checkout situé dans le répertoire de l’environnement isolé vers la branche `rudel/{id}`. `$remote_url` et `$subdir` prennent par défaut les valeurs enregistrées dans l’environnement isolé. Renvoie le SHA du commit, ou `null` si rien n’a changé.

## Automatisation

- `Rudel::run_automation(): array` exécute maintenant les tâches d’automatisation planifiées.
- `Rudel::run_scheduled_cleanup(): array` fait de même.

Voir [Automatisation](https://rudel.inline0.dev/fr/docs/features/automation).

## Référentiel des hooks et des commandes

- `Rudel::hooks(): array` renvoie le référentiel documenté des hooks, indexé par nom de hook. Voir [Hooks](https://rudel.inline0.dev/fr/docs/features/hooks).
- `Rudel::cli_command_map(): array` renvoie une description sérialisable de chaque commande `wp rudel` et de la méthode PHP correspondante.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` transforme une commande analysée en un plan d’exécution sans l’exécuter.

```php
$plan = Rudel::resolve_cli_command( 'wp rudel destroy', [ 'alpha-3be7' ] );
// $plan['callable']           => 'Rudel\Rudel::destroy'
// $plan['arguments']          => [ 'alpha-3be7' ]
// $plan['needs_confirmation'] => true
```

La plupart des plans utilisent le transport `php`. `logs --follow` correspond à un plan `shell` exécuté par `tail -f`.

## Initialisation autonome

### `Rudel::init( Connection $connection, array $context = [] ): void`

Configure la façade pour utiliser une connexion MySQL directe en dehors de WordPress. `$context` accepte `environments_dir`.

```php
use Rudel\Connection;
use Rudel\Rudel;

Rudel::init(
    new Connection( '127.0.0.1', 'wordpress', 'root', 'root', 'wp_' ),
    [ 'environments_dir' => '/var/www/html/wp-content/rudel-environments' ]
);
```

- `Rudel::ensure_schema(): void` crée les tables Rudel pour la connexion active.
- `Rudel::reset(): void` efface la connexion autonome et l’état mis en cache.