# API

`Rudel\Rudel` je statični fasadni razred. Vsaka metoda na tej strani je javna statična metoda tega razreda.

```php
use Rudel\Rudel;

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

Metode življenjskega cikla, ki klonirajo ali odstranijo tabele (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), potrebujejo aktiven zahtevek WordPress z `$wpdb`. Če jih pokličete po `Rudel::init()` zunaj WordPress, sprožijo `RuntimeException`. Glejte [Samostojna uporaba](https://rudel.inline0.dev/sl/docs/features/standalone-use).

## Kontekst izvajanja

Te metode opisujejo trenutni zahtevek. Zunaj peskovnika vrnejo `false` ali `null`.

| Metoda | Vrne |
|--------|---------|
| `is_sandbox(): bool` | `true`, če se trenutni zahtevek izvaja znotraj peskovnika |
| `id(): ?string` | ID trenutnega peskovnika |
| `path(): ?string` | trenutni imenik peskovnika |
| `engine(): ?string` | `overlay` znotraj peskovnika |
| `table_prefix(): ?string` | predpona tabel peskovnika, na primer `wp_b65338d_` |
| `url(): ?string` | URL peskovnika; prekrivni peskovniki si delijo gostiteljski URL |
| `exit_url(): string` | gostiteljski URL |
| `is_email_disabled(): bool` | `true`, kadar je odhodna pošta za zahtevek blokirana |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | nameščena različica Rudel |
| `cli_command(): string` | korenski ukaz WP-CLI, razen če je nastavljen `RUDEL_CLI_COMMAND` `rudel` |

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

Vrne vse zgoraj navedeno v eni matriki:

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

Vrne enak povzetek izvajalnega okolja kot `wp rudel status` v obliki matrike: stanje zagona, trenutni peskovnik, imenik peskovnikov in njihovo število, vrednosti `rudel_config` ter podatek, ali je avtomatizacija načrtovana.

## Zapisi peskovnikov

Peskovniki so vrnjeni kot objekti `Rudel\Environment`. Med uporabnimi lastnostmi samo za branje so `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` in `clone_source`. Metode vključujejo `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` in `to_array()`.

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

Vrne vse peskovnike kot matriko objektov `Environment`. Filtrov ne sprejme.

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

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

Naloži peskovnik po ID-ju ali vrne `null`.

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

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

Vrne imenik, v katerem so shranjeni imeniki peskovnikov.

## Življenjski cikel

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

Ustvari peskovnik in ga vrne. ID se ustvari iz imena in štirih šestnajstiških znakov.

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

Možnosti:

| Ključ | Pomen |
|-----|---------|
| `theme` | oznaka teme, ki jo kopirate v peskovnik; privzeto aktivna tema gostitelja |
| `clone_from` | ID obstoječega peskovnika, ki ga klonirate namesto gostitelja |
| `owner`, `purpose` | metapodatki v prosti obliki |
| `labels` | matrika ali niz, ločen z vejicami |
| `protected` | `true` za izvzetje peskovnika iz čiščenja |
| `ttl_days` | čas poteka glede na čas ustvarjanja |
| `expires_at` | izrecen časovni žig poteka |
| `template` | oznaka, shranjena v zapisu; ne naloži shranjene predloge |
| `site_options` | imena možnosti in skalarne vrednosti, zapisane v tabelo možnosti peskovnika |
| `skip_limits` | `true` za obhod `max_sandboxes` in `max_disk_mb` |

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

Ustvari peskovnik in vanj klonira `$remote_url`. Sprejme možnosti `create()` ter `name` (privzeto ime repozitorija) in `type` (`theme` ali `plugin`). Vrne `[ 'environment' => Environment, 'git' => [...] ]`. Neuspešno kloniranje ne razveljavi ustvarjanja peskovnika; napaka je vrnjena v `git.error`. Glejte [Git](https://rudel.inline0.dev/sl/docs/features/git).

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

Posodobi metapodatke življenjskega cikla in vrne osveženi peskovnik. Med sprejetimi ključi so `owner`, `labels`, `purpose`, `protected`, `ttl_days` (glede na trenutni čas), `expires_at`, `clear_expiry`, `name` in `site_options`.

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

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

Odstrani tabele peskovnika, izbriše njegov imenik in povezane delovne drevesne kopije ter izbriše njegov zapis. Če ID ne obstaja, vrne `false`. Zaščite ne preveri: uniči tudi zaščitene peskovnike.

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

Izvede pravilnik za potek, starost in nedejavnost. Možnosti: `dry_run` (bool), `max_age_days` in `max_idle_days` (nadomestijo `rudel_config`, če niso nič). Vrne `removed`, `skipped`, `errors` in `reasons` (ID do `expired`, `age`, `idle` ali `protected`). Glejte [Čiščenje](https://rudel.inline0.dev/sl/docs/features/cleanup).

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

Odstrani peskovnike, katerih povezane veje delovnih dreves Git so združene v privzeto vejo repozitorija. Možnost: `dry_run`.

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

Zabeleži dejavnost (`last_used_at`) za trenutni peskovnik. Rudel to pokliče pri vsakem zahtevku peskovnika.

## Dnevniki

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

Vrne zadnje vrstice dnevnika peskovnika `debug.log` kot `path`, `exists`, `empty`, `total_lines` in `lines`.

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

Izprazni dnevnik peskovnika `debug.log` in vrne `path`, `existed` ter `cleared`.

## Posnetki stanja

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

Ustvari posnetek stanja in vrne njegove metapodatke (`name`, `created_at`, `sandbox_id`).

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

Obnovi posnetek stanja. Pri privzeti nastavitvi `auto_snapshot_before_restore` Rudel najprej shrani posnetek stanja `pre-restore-...`.

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

Navede metapodatke posnetkov stanja, od najnovejšega naprej. Glejte [Posnetki stanja](https://rudel.inline0.dev/sl/docs/features/snapshots).

## Predloge

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

Shranjene predloge so samo kopije datotek. Noben API ali ukaz ne ustvari peskovnika iz predloge. Glejte [Predloge](https://rudel.inline0.dev/sl/docs/features/templates).

## Git

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

Potrdi in potisne odjavo znotraj imenika peskovnika v vejo `rudel/{id}`. `$remote_url` in `$subdir` sta privzeto nastavljena na vrednosti, shranjene v peskovniku. Vrne SHA potrditve ali `null`, če ni bilo sprememb.

## Avtomatizacija

- `Rudel::run_automation(): array` zdaj zažene načrtovana opravila avtomatizacije.
- `Rudel::run_scheduled_cleanup(): array` naredi enako.

Glejte [Avtomatizacija](https://rudel.inline0.dev/sl/docs/features/automation).

## Kljuke in katalog ukazov

- `Rudel::hooks(): array` vrne dokumentiran katalog kljuk, razvrščen po imenu kljuke. Glejte [Kljuke](https://rudel.inline0.dev/sl/docs/features/hooks).
- `Rudel::cli_command_map(): array` vrne serializabilen opis vsakega ukaza `wp rudel` in metode PHP, ki stoji za njim.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` spremeni en razčlenjen ukaz v načrt izvajanja, ne da bi ga izvedel.

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

Večina načrtov uporablja prenos `php`. `logs --follow` se razreši v načrt `shell`, ki se izvaja `tail -f`.

## Samostojna inicializacija

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

Usmeri fasado na neposredno povezavo MySQL za uporabo zunaj WordPress. `$context` sprejme `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` ustvari tabele Rudel za aktivno povezavo.
- `Rudel::reset(): void` počisti samostojno povezavo in predpomnjeno stanje.