# API

`Rudel\Rudel` yra statinė fasadinė klasė. Kiekvienas šiame puslapyje aprašytas metodas yra viešas statinis šios klasės metodas.

```php
use Rudel\Rudel;

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

Gyvavimo ciklo metodams, kurie klonuoja arba pašalina lenteles (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), reikia aktyvios WordPress užklausos su `$wpdb`. Jei jie iškviečiami po `Rudel::init()`, už WordPress ribų, išmetama `RuntimeException`. Žr. [Atskiras naudojimas](https://rudel.inline0.dev/lt/docs/features/standalone-use).

## Vykdymo aplinka

Šie metodai aprašo dabartinę užklausą. Už smėliadėžės ribų jie grąžina `false` arba `null`.

| Metodas | Grąžina |
|--------|---------|
| `is_sandbox(): bool` | `true`, jei dabartinė užklausa vykdoma smėliadėžėje |
| `id(): ?string` | Dabartinės smėliadėžės ID |
| `path(): ?string` | Dabartinės smėliadėžės katalogas |
| `engine(): ?string` | `overlay` smėliadėžėje |
| `table_prefix(): ?string` | Smėliadėžės lentelių prefiksas, pavyzdžiui, `wp_b65338d_` |
| `url(): ?string` | Smėliadėžės URL; perdangos smėliadėžės naudoja bendrą prieglobos URL |
| `exit_url(): string` | Prieglobos URL |
| `is_email_disabled(): bool` | `true`, kai užklausoje blokuojamas siunčiamas paštas |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | Įdiegta Rudel versija |
| `cli_command(): string` | Pagrindinė WP-CLI komanda, `rudel`, nebent nustatytas `RUDEL_CLI_COMMAND` |

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

Grąžina visa tai viename masyve:

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

Grąžina tą pačią vykdymo aplinkos suvestinę kaip `wp rudel status`, masyvo pavidalu: inicijavimo būseną, dabartinę smėliadėžę, smėliadėžių katalogą ir skaičių, `rudel_config` reikšmes bei informaciją, ar automatizavimas suplanuotas.

## Smėliadėžių įrašai

Smėliadėžės grąžinamos kaip `Rudel\Environment` objektai. Naudingos tik skaityti skirtos savybės: `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` ir `clone_source`. Metodai: `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` ir `to_array()`.

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

Grąžina visas smėliadėžes kaip `Environment` objektų masyvą. Filtrų nėra.

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

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

Pagal ID įkelia vieną smėliadėžę arba grąžina `null`.

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

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

Grąžina katalogą, kuriame laikomi smėliadėžių katalogai.

## Gyvavimo ciklas

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

Sukuria smėliadėžę ir ją grąžina. ID sudaromas iš pavadinimo ir keturių šešioliktainių simbolių.

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

Parinktys:

| Raktas | Reikšmė |
|-----|---------|
| `theme` | Temai skirtas identifikatorius, kopijuojamas į smėliadėžę; numatytoji reikšmė – aktyvi prieglobos tema |
| `clone_from` | Esamos smėliadėžės, klonuojamos vietoj prieglobos, ID |
| `owner`, `purpose` | Laisvojo teksto metaduomenys |
| `labels` | Masyvas arba kableliais atskirta eilutė |
| `protected` | `true`, kad smėliadėžė nebūtų pašalinta valant |
| `ttl_days` | Galiojimo pabaiga nuo sukūrimo laiko |
| `expires_at` | Aiškiai nurodyta galiojimo pabaigos laiko žyma |
| `template` | Įraše saugoma žyma; ji neįkelia išsaugoto šablono |
| `site_options` | Parinkčių pavadinimai ir skaliarinės reikšmės, įrašomos į smėliadėžės parinkčių lentelę |
| `skip_limits` | `true`, kad būtų apeiti `max_sandboxes` ir `max_disk_mb` |

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

Sukuria smėliadėžę, tada į ją klonuoja `$remote_url`. Priima parinktis `create()`, taip pat `name` (numatytoji reikšmė – saugyklos pavadinimas) ir `type` (`theme` arba `plugin`). Grąžina `[ 'environment' => Environment, 'git' => [...] ]`. Nepavykus klonuoti smėliadėžė neatkuriama; klaida grąžinama laukelyje `git.error`. Žr. [GitSmėliadėžių klonavimas](https://rudel.inline0.dev/lt/docs/features/git).

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

Atnaujina gyvavimo ciklo metaduomenis ir grąžina atnaujintą smėliadėžę. Priimami raktai: `owner`, `labels`, `purpose`, `protected`, `ttl_days` (nuo dabar), `expires_at`, `clear_expiry`, `name` ir `site_options`.

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

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

Pašalina smėliadėžės lenteles, jos katalogą ir susietus darbinius medžius bei ištrina įrašą. Jei ID neegzistuoja, grąžina `false`. Apsaugos netikrinamos: sunaikinamos ir apsaugotos smėliadėžės.

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

Taiko galiojimo pabaigos, amžiaus ir neaktyvumo politiką. Parinktys: `dry_run` (loginė reikšmė), `max_age_days` ir `max_idle_days` (kai reikšmė nelygi nuliui, pakeičia `rudel_config`). Grąžina `removed`, `skipped`, `errors` ir `reasons` (ID susietas su `expired`, `age`, `idle` arba `protected`). Žr. [Valymas](https://rudel.inline0.dev/lt/docs/features/cleanup).

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

Pašalina smėliadėžes, kurių susietos Git darbinio medžio šakos sujungtos su numatytąja saugyklos šaka. Parinktis: `dry_run`.

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

Įrašo dabartinės smėliadėžės veiklą (`last_used_at`). Rudel tai atlieka kiekvienai smėliadėžės užklausai.

## Žurnalai

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

Grąžina paskutines smėliadėžės `debug.log` eilutes kaip `path`, `exists`, `empty`, `total_lines` ir `lines`.

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

Išvalo smėliadėžės `debug.log` ir grąžina `path`, `existed` ir `cleared`.

## Momentinės kopijos

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

Sukuria momentinę kopiją ir grąžina jos metaduomenis (`name`, `created_at`, `sandbox_id`).

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

Atkuria momentinę kopiją. Naudojant numatytąjį nustatymą `auto_snapshot_before_restore`, Rudel pirmiausia išsaugo `pre-restore-...` momentinę kopiją.

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

Pateikia momentinių kopijų metaduomenis, pradedant naujausiais. Žr. [Momentinės kopijos](https://rudel.inline0.dev/lt/docs/features/snapshots).

## Šablonai

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

Išsaugoti šablonai yra tik failų kopijos. Jokia API ar komanda nesukuria smėliadėžės iš šablono. Žr. [Šablonai](https://rudel.inline0.dev/lt/docs/features/templates).

## Git

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

Įrašo pakeitimus ir išsiunčia smėlio dėžėje esantį darbinį medį į šaką `rudel/{id}`. `$remote_url` ir `$subdir` pagal numatytuosius nustatymus naudoja smėlio dėžėje išsaugotas reikšmes. Grąžina įrašo SHA arba `null`, jei pakeitimų nebuvo.

## Automatizavimas

- `Rudel::run_automation(): array` dabar paleidžia suplanuotas automatizavimo užduotis.
- `Rudel::run_scheduled_cleanup(): array` atlieka tą patį.

Žr. [Automatizavimas](https://rudel.inline0.dev/lt/docs/features/automation).

## Kabliukai ir komandų katalogas

- `Rudel::hooks(): array` grąžina dokumentuotą kabliukų katalogą, surikiuotą pagal kabliuko pavadinimą. Žr. [Kabliukai](https://rudel.inline0.dev/lt/docs/features/hooks).
- `Rudel::cli_command_map(): array` grąžina serializuojamą kiekvienos `wp rudel` komandos ir už jos esančio PHP metodo aprašą.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` paverčia vieną išanalizuotą komandą vykdymo planu jos nepaleisdamas.

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

Dauguma planų naudoja `php` transportą. `logs --follow` išsprendžiamas į `shell` planą, vykdomą `tail -f`.

## Atskiras inicijavimas

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

Nukreipia fasadą į tiesioginį MySQL ryšį, skirtą naudoti už WordPress ribų. `$context` priima `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` sukuria aktyvaus ryšio Rudel lenteles.
- `Rudel::reset(): void` išvalo atskirą ryšį ir talpyklos būseną.