# API

`Rudel\Rudel` er en statisk facade. Alle metoder på denne side er offentlige statiske metoder i den klasse.

```php
use Rudel\Rudel;

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

Livscyklusmetoder, der kloner eller fjerner tabeller (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), kræver en aktiv WordPress-anmodning med `$wpdb`. De udløser en `RuntimeException`, hvis de kaldes efter `Rudel::init()` uden for WordPress. Se [Selvstændig brug](https://rudel.inline0.dev/da/docs/features/standalone-use).

## Runtimekontekst

Disse metoder beskriver den aktuelle anmodning. Uden for en sandbox returnerer de `false` eller `null`.

| Metode | Returnerer |
|--------|---------|
| `is_sandbox(): bool` | `true`, når den aktuelle anmodning kører i en sandbox |
| `id(): ?string` | det aktuelle sandbox-id |
| `path(): ?string` | den aktuelle sandbox-mappe |
| `engine(): ?string` | `overlay` i en sandbox |
| `table_prefix(): ?string` | sandboxens tabelpræfiks, for eksempel `wp_b65338d_` |
| `url(): ?string` | sandboxens URL; overlay-sandboxes deler værtens URL |
| `exit_url(): string` | værtens URL |
| `is_email_disabled(): bool` | `true`, når udgående mail er blokeret for anmodningen |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | den installerede version af Rudel |
| `cli_command(): string` | rodkommandoen for WP-CLI, `rudel`, medmindre `RUDEL_CLI_COMMAND` er angivet |

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

Returnerer alt ovenstående i ét 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`

Returnerer det samme runtime-resumé som `wp rudel status` i et array: bootstrapstatus, den aktuelle sandbox, sandboxmappen og antallet af sandboxes, værdierne for `rudel_config` samt om automatisering er planlagt.

## Sandbox-poster

Sandboxes returneres som `Rudel\Environment`-objekter. Nyttige skrivebeskyttede egenskaber omfatter `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` og `clone_source`. Metoder omfatter `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` og `to_array()`.

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

Returnerer hver sandbox som et array af `Environment`-objekter. Der kan ikke angives filtre.

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

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

Indlæser en sandbox efter id eller returnerer `null`.

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

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

Returnerer mappen, der indeholder sandbox-mapperne.

## Livscyklus

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

Opretter en sandbox og returnerer den. Id'et genereres ud fra navnet plus fire hexadecimale tegn.

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

Indstillinger:

| Nøgle | Betydning |
|-----|---------|
| `theme` | temaskriden, der skal kopieres til sandboxen; standarden er værtens aktive tema |
| `clone_from` | id på en eksisterende sandbox, der skal klones i stedet for værten |
| `owner`, `purpose` | fritekstmetadata |
| `labels` | array eller kommasepareret streng |
| `protected` | `true` for at undtage sandboxen fra oprydning |
| `ttl_days` | udløbstid regnet fra oprettelsestidspunktet |
| `expires_at` | eksplicit tidsstempel for udløb |
| `template` | en etiket gemt på posten; den indlæser ikke en gemt skabelon |
| `site_options` | indstillingsnavne og skalarværdier, der skrives til sandboxens indstillingstabel |
| `skip_limits` | `true` for at omgå `max_sandboxes` og `max_disk_mb` |

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

Opretter en sandbox og kloner derefter `$remote_url` ind i den. Accepterer indstillingerne for `create()` plus `name` (standard er arkivets navn) og `type` (`theme` eller `plugin`). Returnerer `[ 'environment' => Environment, 'git' => [...] ]`. En mislykket kloning ruller ikke sandboxen tilbage; fejlen returneres i `git.error`. Se [Git](https://rudel.inline0.dev/da/docs/features/git).

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

Opdaterer livscyklusmetadata og returnerer den opdaterede sandbox. Accepterede nøgler omfatter `owner`, `labels`, `purpose`, `protected`, `ttl_days` (regnet fra nu), `expires_at`, `clear_expiry`, `name` og `site_options`.

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

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

Fjerner sandboxens tabeller, sletter dens mappe og tilknyttede worktrees og sletter posten. Returnerer `false`, hvis id'et ikke findes. Beskyttelsen kontrolleres ikke: beskyttede sandboxes slettes også.

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

Kører politikken for udløb, alder og inaktivitet. Indstillinger: `dry_run` (bool), `max_age_days` og `max_idle_days` (tilsidesætter `rudel_config`, når værdien ikke er nul). Returnerer `removed`, `skipped`, `errors` og `reasons` (id til `expired`, `age`, `idle` eller `protected`). Se [Oprydning](https://rudel.inline0.dev/da/docs/features/cleanup).

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

Fjerner sandboxes, hvis tilknyttede Git-worktree-grene er flettet ind i arkivets standardgren. Indstilling: `dry_run`.

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

Registrerer aktivitet (`last_used_at`) for den aktuelle sandbox. Rudel kalder den ved hver sandbox-anmodning.

## Logfiler

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

Returnerer de sidste linjer i sandboxens `debug.log` som `path`, `exists`, `empty`, `total_lines` og `lines`.

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

Tømmer sandboxens `debug.log` og returnerer `path`, `existed` og `cleared`.

## Snapshots

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

Opretter et snapshot og returnerer dets metadata (`name`, `created_at`, `sandbox_id`).

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

Gendanner et snapshot. Med standardindstillingen `auto_snapshot_before_restore` gemmer Rudel først et `pre-restore-...`-snapshot.

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

Viser snapshotmetadata med det nyeste først. Se [Snapshots](https://rudel.inline0.dev/da/docs/features/snapshots).

## Skabeloner

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

Gemte skabeloner er kun filkopier. Ingen API eller kommando opretter en sandbox ud fra en skabelon. Se [Skabeloner](https://rudel.inline0.dev/da/docs/features/templates).

## Git

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

Committer og pusher en checkout i sandboxmappen til grenen `rudel/{id}`. `$remote_url` og `$subdir` bruger som standard værdierne gemt i sandboxen. Returnerer commit-SHA'en eller `null`, hvis intet er ændret.

## Automatisering

- `Rudel::run_automation(): array` kører de planlagte automatiseringsopgaver nu.
- `Rudel::run_scheduled_cleanup(): array` gør det samme.

Se [Automatisering](https://rudel.inline0.dev/da/docs/features/automation).

## Hooks og kommandokatalog

- `Rudel::hooks(): array` returnerer det dokumenterede hook-katalog med hooknavne som nøgler. Se [Hooks](https://rudel.inline0.dev/da/docs/features/hooks).
- `Rudel::cli_command_map(): array` returnerer en serialiserbar beskrivelse af hver `wp rudel`-kommando og metoden PHP bag den.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` omdanner én fortolket kommando til en udførelsesplan uden at køre den.

```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 fleste planer bruger transporten `php`. `logs --follow` opløses til en `shell`-plan, der kører `tail -f`.

## Selvstændig initialisering

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

Retter facaden mod en direkte MySQL-forbindelse til brug uden for WordPress. `$context` accepterer `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` opretter Rudel-tabellerne for den aktive forbindelse.
- `Rudel::reset(): void` rydder den selvstændige forbindelse og den cachede tilstand.