# API

`Rudel\Rudel` ist eine statische Fassade. Jede Methode auf dieser Seite ist eine öffentliche statische Methode dieser Klasse.

```php
use Rudel\Rudel;

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

Lebenszyklusmethoden, die Tabellen klonen oder löschen (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), benötigen eine aktive WordPress-Anfrage mit `$wpdb`. Nach `Rudel::init()` außerhalb von WordPress lösen sie einen `RuntimeException` aus. Siehe [Eigenständige Verwendung](https://rudel.inline0.dev/de/docs/features/standalone-use).

## Laufzeitkontext

Diese Methoden beschreiben die aktuelle Anfrage. Außerhalb einer Sandbox geben sie `false` oder `null` zurück.

| Methode | Rückgabewert |
|--------|---------|
| `is_sandbox(): bool` | `true`, wenn die aktuelle Anfrage innerhalb einer Sandbox ausgeführt wird |
| `id(): ?string` | die ID der aktuellen Sandbox |
| `path(): ?string` | das Verzeichnis der aktuellen Sandbox |
| `engine(): ?string` | `overlay` innerhalb einer Sandbox |
| `table_prefix(): ?string` | das Präfix der Sandboxtabelle, zum Beispiel `wp_b65338d_` |
| `url(): ?string` | die Sandbox-URL; Overlay-Sandboxes teilen sich die URL des Hosts |
| `exit_url(): string` | die URL des Hosts |
| `is_email_disabled(): bool` | `true`, wenn ausgehende E-Mails für die Anfrage blockiert werden |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | die installierte Version von Rudel |
| `cli_command(): string` | der WP-CLI-Root-Befehl, `rudel`, sofern `RUDEL_CLI_COMMAND` nicht festgelegt ist |

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

Gibt alles Obige in einem Array zurück:

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

Gibt dieselbe Laufzeitübersicht wie `wp rudel status` als Array zurück: Bootstrap-Status, aktuelle Sandbox, Sandbox-Verzeichnis und -Anzahl, die Werte von `rudel_config` und ob Automatisierung geplant ist.

## Sandbox-Einträge

Sandboxes werden als `Rudel\Environment`-Objekte zurückgegeben. Zu den nützlichen schreibgeschützten Eigenschaften gehören `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` und `clone_source`. Zu den Methoden gehören `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` und `to_array()`.

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

Gibt alle Sandboxes als Array von `Environment`-Objekten zurück. Es können keine Filter angegeben werden.

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

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

Lädt eine Sandbox anhand ihrer ID oder gibt `null` zurück.

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

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

Gibt das Verzeichnis zurück, in dem die Sandbox-Verzeichnisse liegen.

## Lebenszyklus

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

Erstellt eine Sandbox und gibt sie zurück. Die ID wird aus dem Namen und vier Hex-Zeichen gebildet.

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

Optionen:

| Schlüssel | Bedeutung |
|-----|---------|
| `theme` | Theme-Slug, der in die Sandbox kopiert wird; standardmäßig das aktive Theme des Hosts |
| `clone_from` | ID einer bestehenden Sandbox, die statt des Hosts geklont wird |
| `owner`, `purpose` | Freitext-Metadaten |
| `labels` | Array oder durch Kommas getrennte Zeichenfolge |
| `protected` | `true`, um die Sandbox von der Bereinigung auszunehmen |
| `ttl_days` | Ablaufzeit ab dem Erstellungszeitpunkt |
| `expires_at` | Expliziter Ablaufzeitpunkt |
| `template` | Im Eintrag gespeichertes Label; lädt keine gespeicherte Vorlage |
| `site_options` | Optionsnamen und skalare Werte, die in die Optionstabelle der Sandbox geschrieben werden |
| `skip_limits` | `true`, um `max_sandboxes` und `max_disk_mb` zu umgehen |

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

Erstellt eine Sandbox und klont anschließend `$remote_url` hinein. Akzeptiert die Optionen von `create()` sowie `name` (standardmäßig der Repository-Name) und `type` (`theme` oder `plugin`). Gibt `[ 'environment' => Environment, 'git' => [...] ]` zurück. Bei einem fehlgeschlagenen Klon wird die Sandbox nicht zurückgesetzt; der Fehler wird in `git.error` zurückgegeben. Siehe [Git](https://rudel.inline0.dev/de/docs/features/git).

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

Aktualisiert Lebenszyklus-Metadaten und gibt die aktualisierte Sandbox zurück. Zu den akzeptierten Schlüsseln gehören `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relativ zu jetzt), `expires_at`, `clear_expiry`, `name` und `site_options`.

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

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

Löscht die Sandboxtabellen, entfernt ihr Verzeichnis und verknüpfte Worktrees und löscht den Eintrag. Gibt `false` zurück, wenn die ID nicht existiert. Der Schutzstatus wird nicht geprüft: Auch geschützte Sandboxes werden gelöscht.

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

Wendet Ablauf-, Alters- und Inaktivitätsregeln an. Optionen: `dry_run` (bool), `max_age_days` und `max_idle_days` (überschreiben `rudel_config`, wenn der Wert ungleich null ist). Gibt `removed`, `skipped`, `errors` und `reasons` zurück (ID zu `expired`, `age`, `idle` oder `protected`). Siehe [Bereinigung](https://rudel.inline0.dev/de/docs/features/cleanup).

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

Entfernt Sandboxes, deren verknüpfte Git-Worktree-Branches in den Standard-Branch des Repositorys integriert wurden. Option: `dry_run`.

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

Zeichnet Aktivität (`last_used_at`) für die aktuelle Sandbox auf. Rudel ruft dies bei jeder Sandbox-Anfrage auf.

## Protokolle

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

Gibt die letzten Zeilen des Sandbox-`debug.log` als `path`, `exists`, `empty`, `total_lines` und `lines` zurück.

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

Leert das Sandbox-`debug.log` und gibt `path`, `existed` und `cleared` zurück.

## Snapshots

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

Erstellt einen Snapshot und gibt seine Metadaten zurück (`name`, `created_at`, `sandbox_id`).

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

Stellt einen Snapshot wieder her. Bei der Standardeinstellung `auto_snapshot_before_restore` speichert Rudel zuerst einen `pre-restore-...`-Snapshot.

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

Listet Snapshot-Metadaten auf, neueste zuerst. Siehe [Snapshots](https://rudel.inline0.dev/de/docs/features/snapshots).

## Vorlagen

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

Gespeicherte Vorlagen sind lediglich Dateikopien. Kein API und kein Befehl erstellt daraus eine Sandbox. Siehe [Vorlagen](https://rudel.inline0.dev/de/docs/features/templates).

## Git

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

Commitet und pusht einen Checkout im Sandbox-Verzeichnis in den Branch `rudel/{id}`. `$remote_url` und `$subdir` verwenden standardmäßig die in der Sandbox gespeicherten Werte. Gibt die Commit-SHA zurück oder `null`, wenn es keine Änderungen gab.

## Automatisierung

- `Rudel::run_automation(): array` führt die geplanten Automatisierungsaufgaben jetzt aus.
- `Rudel::run_scheduled_cleanup(): array` macht dasselbe.

Siehe [Automatisierung](https://rudel.inline0.dev/de/docs/features/automation).

## Hooks und Befehlsübersicht

- `Rudel::hooks(): array` gibt die dokumentierte Hook-Übersicht nach Hook-Namen sortiert zurück. Siehe [Hooks](https://rudel.inline0.dev/de/docs/features/hooks).
- `Rudel::cli_command_map(): array` gibt eine serialisierbare Beschreibung jedes `wp rudel`-Befehls und der zugehörigen PHP-Methode zurück.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` wandelt einen geparsten Befehl in einen Ausführungsplan um, ohne ihn auszuführen.

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

Die meisten Pläne verwenden den Transport `php`. `logs --follow` wird zu einem `shell`-Plan, der `tail -f` ausführt.

## Eigenständige Initialisierung

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

Verknüpft die Fassade für die Verwendung außerhalb von WordPress mit einer direkten MySQL-Verbindung. `$context` akzeptiert `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` erstellt die Rudel-Tabellen für die aktive Verbindung.
- `Rudel::reset(): void` löscht die eigenständige Verbindung und den zwischengespeicherten Zustand.