# API

`Rudel\Rudel` ir statiska fasāde. Katra šajā lapā aprakstītā metode ir šīs klases publiska statiska metode.

```php
use Rudel\Rudel;

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

Dzīvescikla metodēm, kas klonē vai dzēš tabulas (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), nepieciešams aktīvs WordPress pieprasījums ar `$wpdb`. Ja tās izsauc pēc `Rudel::init()` ārpus WordPress, tiek izraisīts `RuntimeException`. Skatiet [Patstāvīga lietošana](https://rudel.inline0.dev/lv/docs/features/standalone-use).

## Izpildlaika konteksts

Šīs metodes raksturo pašreizējo pieprasījumu. Ārpus smilškastes tās atgriež `false` vai `null`.

| Metode | Atgriež |
|--------|---------|
| `is_sandbox(): bool` | `true`, ja pašreizējais pieprasījums darbojas smilškastē |
| `id(): ?string` | pašreizējās smilškastes ID |
| `path(): ?string` | pašreizējās smilškastes direktoriju |
| `engine(): ?string` | `overlay` smilškastē |
| `table_prefix(): ?string` | smilškastes tabulu prefiksu, piemēram, `wp_b65338d_` |
| `url(): ?string` | smilškastes URL; pārklājuma smilškastēm ir kopīga saimnieka URL |
| `exit_url(): string` | saimnieka URL |
| `is_email_disabled(): bool` | `true`, ja pieprasījumam ir bloķēta izejošā pasta sūtīšana |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | instalēto Rudel versiju |
| `cli_command(): string` | WP-CLI saknes komandu, `rudel`, ja vien nav iestatīts `RUDEL_CLI_COMMAND` |

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

Atgriež visu iepriekš minēto vienā masīvā:

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

Atgriež tādu pašu izpildlaika kopsavilkumu kā `wp rudel status`, masīva formā: sākotnējās ielādes stāvokli, pašreizējo smilškasti, smilškastu direktoriju un skaitu, vērtības `rudel_config` un to, vai ir ieplānota automatizācija.

## Smilškastu ieraksti

Smilškastes tiek atgrieztas kā `Rudel\Environment` objekti. Noderīgas tikai lasāmas īpašības ir `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` un `clone_source`. Metodes ir `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` un `to_array()`.

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

Atgriež katru smilškasti kā `Environment` objektu masīvu. Filtrus nevar norādīt.

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

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

Ielādē smilškasti pēc ID vai atgriež `null`.

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

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

Atgriež direktoriju, kurā atrodas smilškastu direktorijas.

## Dzīves cikls

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

Izveido smilškasti un atgriež to. ID tiek ģenerēts no nosaukuma un četrām heksadecimālām rakstzīmēm.

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

Opcijas:

| Atslēga | Nozīme |
|-----|---------|
| `theme` | smilškastē kopējamās tēmas slug; pēc noklusējuma — saimniekdatora aktīvā tēma |
| `clone_from` | esošas smilškastes ID, ko klonēt saimniekdatora vietā |
| `owner`, `purpose` | brīvā teksta metadati |
| `labels` | masīvs vai ar komatiem atdalīta virkne |
| `protected` | `true`, lai izslēgtu smilškasti no tīrīšanas |
| `ttl_days` | derīguma termiņš no izveides brīža |
| `expires_at` | skaidri norādīta derīguma termiņa laika atzīme |
| `template` | ierakstā saglabāta etiķete; tā neielādē saglabātu veidni |
| `site_options` | opciju nosaukumi un skalārās vērtības, ko ieraksta smilškastes opciju tabulā |
| `skip_limits` | `true`, lai apietu `max_sandboxes` un `max_disk_mb` |

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

Izveido smilškasti un pēc tam tajā klonē `$remote_url`. Pieņem `create()` opcijas, kā arī `name` (pēc noklusējuma — repozitorija nosaukums) un `type` (`theme` vai `plugin`). Atgriež `[ 'environment' => Environment, 'git' => [...] ]`. Ja klonēšana neizdodas, smilškaste netiek atcelta; kļūda tiek atgriezta laukā `git.error`. Skatiet [Git](https://rudel.inline0.dev/lv/docs/features/git).

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

Atjaunina dzīvescikla metadatus un atgriež atsvaidzināto smilškasti. Pieņemtās atslēgas: `owner`, `labels`, `purpose`, `protected`, `ttl_days` (attiecībā pret pašreizējo brīdi), `expires_at`, `clear_expiry`, `name` un `site_options`.

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

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

Dzēš smilškastes tabulas, tās direktoriju un saistītos darba kokus, kā arī tās ierakstu. Ja ID neeksistē, atgriež `false`. Aizsardzība netiek pārbaudīta: tiek iznīcinātas arī aizsargātas smilškastes.

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

Izpilda derīguma termiņa, vecuma un neaktivitātes politiku. Opcijas: `dry_run` (bool), `max_age_days` un `max_idle_days` (ja vērtība nav nulle, ignorē `rudel_config`). Atgriež `removed`, `skipped`, `errors` un `reasons` (ID un `expired`, `age`, `idle` vai `protected`). Skatiet [Tīrīšana](https://rudel.inline0.dev/lv/docs/features/cleanup).

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

Noņem smilškastes, kuru saistīto Git darba koku atzari ir sapludināti repozitorija noklusējuma atzarā. Opcija: `dry_run`.

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

Reģistrē pašreizējās smilškastes darbību (`last_used_at`). Rudel izsauc šo metodi katrā smilškastes pieprasījumā.

## Žurnāli

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

Atgriež pēdējās smilškastes `debug.log` rindas kā `path`, `exists`, `empty`, `total_lines` un `lines`.

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

Iztukšo smilškastes `debug.log` un atgriež `path`, `existed` un `cleared`.

## Momentuzņēmumi

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

Izveido momentuzņēmumu un atgriež tā metadatus (`name`, `created_at`, `sandbox_id`).

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

Atjauno momentuzņēmumu. Ja tiek izmantots noklusējuma iestatījums `auto_snapshot_before_restore`, Rudel vispirms saglabā `pre-restore-...` momentuzņēmumu.

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

Uzskaita momentuzņēmumu metadatus, sākot ar jaunākajiem. Skatiet [Momentuzņēmumi](https://rudel.inline0.dev/lv/docs/features/snapshots).

## Veidnes

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

Saglabātās veidnes ir tikai failu kopijas. Neviens API vai komanda no tām neizveido smilškasti. Skatiet [Veidnes](https://rudel.inline0.dev/lv/docs/features/templates).

## Git

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

Apstiprina un nosūta smilškastes direktorijā esošo darba kopiju uz atzaru `rudel/{id}`. `$remote_url` un `$subdir` pēc noklusējuma izmanto smilškastē saglabātās vērtības. Atgriež apstiprinājuma SHA vai `null`, ja izmaiņu nav.

## Automatizācija

- `Rudel::run_automation(): array` palaiž ieplānotos automatizācijas uzdevumus tūlīt.
- `Rudel::run_scheduled_cleanup(): array` veic to pašu.

Skatiet [Automatizācija](https://rudel.inline0.dev/lv/docs/features/automation).

## Āķi un komandu katalogs

- `Rudel::hooks(): array` atgriež dokumentēto āķu katalogu, kas sakārtots pēc āķa nosaukuma. Skatiet [Āķi](https://rudel.inline0.dev/lv/docs/features/hooks).
- `Rudel::cli_command_map(): array` atgriež serializējamu aprakstu par katru `wp rudel` komandu un tai atbilstošo metodi PHP.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` pārvērš vienu parsētu komandu izpildes plānā, to neizpildot.

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

Lielākajā daļā plānu tiek izmantots transports `php`. `logs --follow` tiek atrisināts kā `shell` plāns, kas darbojas ar `tail -f`.

## Patstāvīga inicializācija

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

Norāda fasādei tiešu MySQL savienojumu lietošanai ārpus WordPress. `$context` pieņem `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` izveido Rudel tabulas aktīvajam savienojumam.
- `Rudel::reset(): void` notīra patstāvīgo savienojumu un kešoto stāvokli.