# API

`Rudel\Rudel` is een statische facade. Elke methode op deze pagina is een publieke statische methode van die klasse.

```php
use Rudel\Rudel;

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

Levenscyclusmethoden die tabellen klonen of verwijderen (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) vereisen een actief WordPress-verzoek met `$wpdb`. Als ze worden aangeroepen nadat `Rudel::init()` buiten WordPress is uitgevoerd, genereren ze een `RuntimeException`. Zie [Zelfstandig gebruik](https://rudel.inline0.dev/nl/docs/features/standalone-use).

## Runtimecontext

Deze methoden beschrijven het huidige verzoek. Buiten een sandbox retourneren ze `false` of `null`.

| Methode | Geeft terug |
|--------|---------|
| `is_sandbox(): bool` | `true` wanneer het huidige verzoek binnen een sandbox wordt uitgevoerd |
| `id(): ?string` | de huidige sandbox-ID |
| `path(): ?string` | de huidige sandboxmap |
| `engine(): ?string` | `overlay` binnen een sandbox |
| `table_prefix(): ?string` | het tabelvoorvoegsel van de sandbox, bijvoorbeeld `wp_b65338d_` |
| `url(): ?string` | de sandbox URL; overlay-sandboxes delen de host-URL |
| `exit_url(): string` | de host-URL |
| `is_email_disabled(): bool` | `true` wanneer uitgaande e-mail voor het verzoek is geblokkeerd |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | de geïnstalleerde versie van Rudel |
| `cli_command(): string` | de rootopdracht van WP-CLI, `rudel` tenzij `RUDEL_CLI_COMMAND` is ingesteld |

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

Geeft al het bovenstaande terug in één array:

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

Geeft hetzelfde runtime-overzicht terug als `wp rudel status`, als array: bootstrapstatus, huidige sandbox, sandboxmap en aantal sandboxes, de waarden van `rudel_config` en of automatisering is ingepland.

## Sandboxrecords

Sandboxes worden teruggegeven als `Rudel\Environment`-objecten. Handige alleen-lezen eigenschappen zijn onder meer `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` en `clone_source`. Methoden zijn onder meer `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` en `to_array()`.

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

Geeft elke sandbox terug als een array van `Environment`-objecten. Accepteert geen filters.

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

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

Laadt één sandbox op basis van ID, of geeft `null` terug.

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

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

Geeft de map terug waarin de sandboxmappen staan.

## Levenscyclus

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

Maakt een sandbox aan en geeft deze terug. De ID wordt gegenereerd op basis van de naam plus vier hexadecimale tekens.

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

Opties:

| Sleutel | Betekenis |
|-----|---------|
| `theme` | themaslug die naar de sandbox wordt gekopieerd; standaard het actieve thema van de host |
| `clone_from` | ID van een bestaande sandbox om te klonen in plaats van de host |
| `owner`, `purpose` | vrije metadata |
| `labels` | array of kommagescheiden tekenreeks |
| `protected` | `true` om de sandbox uit te sluiten van opruiming |
| `ttl_days` | vervaldatum ten opzichte van het aanmaaktijdstip |
| `expires_at` | expliciet tijdstip van verval |
| `template` | een label dat in het record wordt opgeslagen; hiermee wordt geen opgeslagen sjabloon geladen |
| `site_options` | optienamen en scalaire waarden die naar de optietabel van de sandbox worden geschreven |
| `skip_limits` | `true` om `max_sandboxes` en `max_disk_mb` te omzeilen |

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

Maakt een sandbox aan en kloont vervolgens `$remote_url` daarin. Accepteert de opties `create()` plus `name` (standaard de repositorynaam) en `type` (`theme` of `plugin`). Geeft `[ 'environment' => Environment, 'git' => [...] ]` terug. Een mislukte kloonactie draait het aanmaken van de sandbox niet terug; de fout wordt teruggegeven in `git.error`. Zie [Git](https://rudel.inline0.dev/nl/docs/features/git).

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

Werkt de levenscyclusmetadata bij en geeft de vernieuwde sandbox terug. Geaccepteerde sleutels zijn onder meer `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relatief ten opzichte van nu), `expires_at`, `clear_expiry`, `name` en `site_options`.

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

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

Verwijdert de sandboxtabellen, de sandboxmap en gekoppelde worktrees, en verwijdert het record. Geeft `false` terug als de ID niet bestaat. Er wordt niet gecontroleerd op bescherming: ook beschermde sandboxes worden vernietigd.

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

Past het beleid voor verval, leeftijd en inactiviteit toe. Opties: `dry_run` (bool), `max_age_days` en `max_idle_days` (overschrijven `rudel_config` wanneer deze niet nul is). Geeft `removed`, `skipped`, `errors` en `reasons` terug (ID naar `expired`, `age`, `idle` of `protected`). Zie [Opruiming](https://rudel.inline0.dev/nl/docs/features/cleanup).

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

Verwijdert sandboxes waarvan de gekoppelde Git-worktreebranches zijn samengevoegd met de standaardbranch van de repository. Optie: `dry_run`.

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

Registreert activiteit (`last_used_at`) voor de huidige sandbox. Rudel roept dit aan bij elk sandboxverzoek.

## Logboeken

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

Geeft de laatste regels van het sandbox-`debug.log` terug als `path`, `exists`, `empty`, `total_lines` en `lines`.

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

Leegt het sandbox-`debug.log` en geeft `path`, `existed` en `cleared` terug.

## Momentopnamen

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

Maakt een momentopname en geeft de metadata terug (`name`, `created_at`, `sandbox_id`).

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

Zet een momentopname terug. Met de standaardinstelling `auto_snapshot_before_restore` slaat Rudel eerst een `pre-restore-...`-momentopname op.

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

Geeft metadata van momentopnamen weer, nieuwste eerst. Zie [Momentopnamen](https://rudel.inline0.dev/nl/docs/features/snapshots).

## Sjablonen

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

Opgeslagen sjablonen zijn uitsluitend bestandskopieën. Geen API of opdracht maakt een sandbox op basis daarvan aan. Zie [Sjablonen](https://rudel.inline0.dev/nl/docs/features/templates).

## Git

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

Commit en pusht een checkout in de sandboxmap naar de branch `rudel/{id}`. `$remote_url` en `$subdir` gebruiken standaard de waarden die in de sandbox zijn opgeslagen. Geeft de commit-SHA terug, of `null` als er niets is gewijzigd.

## Automatisering

- `Rudel::run_automation(): array` voert de ingeplande automatiseringstaken nu uit.
- `Rudel::run_scheduled_cleanup(): array` doet hetzelfde.

Zie [Automatisering](https://rudel.inline0.dev/nl/docs/features/automation).

## Hooks en opdrachtencatalogus

- `Rudel::hooks(): array` geeft de gedocumenteerde hookcatalogus terug, gerangschikt op hooknaam. Zie [Hooks](https://rudel.inline0.dev/nl/docs/features/hooks).
- `Rudel::cli_command_map(): array` geeft een serialiseerbare beschrijving terug van elke `wp rudel`-opdracht en de PHP-methode erachter.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` zet één geparseerde opdracht om in een uitvoeringsplan zonder deze uit te voeren.

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

De meeste plannen gebruiken het transport `php`. `logs --follow` wordt omgezet in een `shell`-plan dat `tail -f` uitvoert.

## Zelfstandige initialisatie

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

Richt de facade op een directe MySQL-verbinding voor gebruik buiten WordPress. `$context` accepteert `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` maakt de Rudel-tabellen aan voor de actieve verbinding.
- `Rudel::reset(): void` wist de zelfstandige verbinding en de gecachte status.