# API

`Rudel\Rudel` on staatiline fassaad. Kõik sellel lehel loetletud meetodid on selle klassi avalikud staatilised meetodid.

```php
use Rudel\Rudel;

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

Elutsükli meetodid, mis kloonivad või eemaldavad tabeleid (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), vajavad aktiivset WordPress-i päringut ja `$wpdb`-i. Kui neid kutsutakse pärast `Rudel::init()`-i väljaspool WordPress-i, viskavad need vea `RuntimeException`. Vt [Eraldiseisev kasutus](https://rudel.inline0.dev/et/docs/features/standalone-use).

## Käituskontekst

Need meetodid kirjeldavad praegust päringut. Väljaspool liivakasti tagastavad need `false` või `null`.

| Meetod | Tagastusväärtus |
|--------|---------|
| `is_sandbox(): bool` | `true`, kui praegune päring töötab liivakastis |
| `id(): ?string` | praeguse liivakasti ID |
| `path(): ?string` | praeguse liivakasti kataloog |
| `engine(): ?string` | `overlay` liivakastis |
| `table_prefix(): ?string` | liivakasti tabelite eesliide, näiteks `wp_b65338d_` |
| `url(): ?string` | liivakasti URL; ülekattega liivakastid jagavad hosti URL-i |
| `exit_url(): string` | hosti URL |
| `is_email_disabled(): bool` | `true`, kui päringust väljaminev e-post on blokeeritud |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | paigaldatud Rudel versioon |
| `cli_command(): string` | WP-CLI juurkäsk `rudel`, kui pole määratud `RUDEL_CLI_COMMAND` |

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

Tagastab kõik eeltoodu ühes massiivis:

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

Tagastab sama käitusaja kokkuvõtte kui `wp rudel status` massiivina: alglaadimise olek, praegune liivakast, liivakastide kataloog ja arv, väärtused `rudel_config` ning teave selle kohta, kas automatiseerimine on ajastatud.

## Liivakasti kirjed

Liivakastid tagastatakse objektidena `Rudel\Environment`. Kasulikud kirjutuskaitstud atribuudid on `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` ja `clone_source`. Meetodite hulka kuuluvad `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` ja `to_array()`.

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

Tagastab kõik liivakastid massiivina, mis koosneb `Environment` objektidest. Filtreid ei kasutata.

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

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

Laadib liivakasti ID järgi või tagastab väärtuse `null`.

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

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

Tagastab liivakasti kataloogi, kus hoitakse liivakastide katalooge.

## Elutsükkel

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

Loob liivakasti ja tagastab selle. ID moodustatakse nimest ja neljast kuueteistkümnendmärgist.

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

Valikud:

| Võti | Tähendus |
|-----|---------|
| `theme` | liivakasti kopeeritava teema lühinimi; vaikimisi hosti aktiivne teema |
| `clone_from` | olemasoleva liivakasti ID, mida kloonida hosti asemel |
| `owner`, `purpose` | vabatekstiline metaandmestik |
| `labels` | massiiv või komadega eraldatud string |
| `protected` | `true`, millega jäetakse liivakast puhastamisest välja |
| `ttl_days` | aegumine loomise hetkest arvates |
| `expires_at` | selgesõnaline aegumisaja ajatempel |
| `template` | kirjele salvestatav silt; see ei laadi salvestatud malli |
| `site_options` | valikute nimed ja skalaarväärtused, mis kirjutatakse liivakasti valikute tabelisse |
| `skip_limits` | `true`, millega möödutakse tingimustest `max_sandboxes` ja `max_disk_mb` |

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

Loob liivakasti ja kloonib sellesse seejärel `$remote_url`. Võtab vastu valikud `create()` ning `name` (vaikimisi hoidla nimi) ja `type` (`theme` või `plugin`). Tagastab väärtuse `[ 'environment' => Environment, 'git' => [...] ]`. Klooni loomise nurjumisel liivakasti tagasi ei võeta; viga tagastatakse väljas `git.error`. Vt [Git](https://rudel.inline0.dev/et/docs/features/git).

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

Uuendab elutsükli metaandmeid ja tagastab värskendatud liivakasti. Lubatud võtmed on muu hulgas `owner`, `labels`, `purpose`, `protected`, `ttl_days` (praegusest hetkest arvates), `expires_at`, `clear_expiry`, `name` ja `site_options`.

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

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

Eemaldab liivakasti tabelid, kataloogi ja lingitud tööpuud ning kustutab kirje. Kui ID-d pole olemas, tagastab väärtuse `false`. Kaitset ei kontrollita: hävitatakse ka kaitstud liivakastid.

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

Rakendab aegumise, vanuse ja jõudeoleku eeskirju. Valikud: `dry_run` (tõeväärtus), `max_age_days` ja `max_idle_days` (nullist erineva väärtuse korral alistavad valiku `rudel_config`). Tagastab väärtused `removed`, `skipped`, `errors` ja `reasons` (ID väärtuse `expired`, `age`, `idle` või `protected` jaoks). Vt [Puhastamine](https://rudel.inline0.dev/et/docs/features/cleanup).

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

Eemaldab liivakastid, mille lingitud Git tööpuu harud on ühendatud hoidla vaikeharuga. Valik: `dry_run`.

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

Salvestab praeguse liivakasti tegevuse (`last_used_at`). Rudel kutsub selle igal liivakasti päringul välja.

## Logid

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

Tagastab liivakasti `debug.log` viimased read väljadena `path`, `exists`, `empty`, `total_lines` ja `lines`.

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

Tühjendab liivakasti `debug.log` ning tagastab väljad `path`, `existed` ja `cleared`.

## Hetktõmmised

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

Loob hetktõmmise ja tagastab selle metaandmed (`name`, `created_at`, `sandbox_id`).

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

Taastab hetktõmmise. Vaikeseadega `auto_snapshot_before_restore` salvestab Rudel esmalt hetktõmmise `pre-restore-...`.

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

Loetleb hetktõmmiste metaandmed, alustades uusimast. Vt [Hetktõmmised](https://rudel.inline0.dev/et/docs/features/snapshots).

## Mallid

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

Salvestatud mallid sisaldavad ainult failikoopiaid. Ükski API ega käsk ei loo nende põhjal liivakasti. Vt [Mallid](https://rudel.inline0.dev/et/docs/features/templates).

## Git

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

Salvestab sissekanded ja lükkab liivakasti kataloogi checkout'i harusse `rudel/{id}`. `$remote_url` ja `$subdir` vaikeväärtused võetakse liivakasti salvestatud väärtustest. Tagastab sissekande SHA või väärtuse `null`, kui muudatusi polnud.

## Automatiseerimine

- `Rudel::run_automation(): array` käivitab ajastatud automatiseerimisülesanded kohe.
- `Rudel::run_scheduled_cleanup(): array` teeb sama.

Vt [Automatiseerimine](https://rudel.inline0.dev/et/docs/features/automation).

## Hook'ide ja käskude kataloog

- `Rudel::hooks(): array` tagastab dokumenteeritud hook'ide kataloogi hook'i nime järgi. Vt [Hook'id](https://rudel.inline0.dev/et/docs/features/hooks).
- `Rudel::cli_command_map(): array` tagastab serialiseeritava kirjelduse iga käsu `wp rudel` ja selle taga oleva meetodi PHP kohta.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` teisendab parsitud käsu täitmisplaaniks seda käivitamata.

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

Enamik plaane kasutab edastuseks meetodit `php`. `logs --follow` lahendatakse plaaniks `shell`, mis käivitub käsuga `tail -f`.

## Eraldiseisev lähtestamine

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

Suunab fassaadi otseühendusele MySQL, et seda kasutada väljaspool WordPress-i. `$context` aktsepteerib väärtust `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` loob aktiivse ühenduse jaoks tabelid Rudel.
- `Rudel::reset(): void` tühjendab eraldiseisva ühenduse ja vahemällu salvestatud oleku.