# API

`Rudel\Rudel` je statická fasáda. Každá metóda na tejto stránke je verejnou statickou metódou tejto triedy.

```php
use Rudel\Rudel;

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

Metódy životného cyklu, ktoré klonujú alebo odstraňujú tabuľky (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), vyžadujú aktívnu požiadavku WordPress s `$wpdb`. Ak sa zavolajú po `Rudel::init()` mimo WordPress, vyhodia `RuntimeException`. Pozrite si [Samostatné použitie](https://rudel.inline0.dev/sk/docs/features/standalone-use).

## Kontext behu

Tieto metódy opisujú aktuálnu požiadavku. Mimo sandboxu vracajú `false` alebo `null`.

| Metóda | Vráti |
|--------|---------|
| `is_sandbox(): bool` | `true`, ak aktuálna požiadavka beží v sandboxe |
| `id(): ?string` | ID aktuálneho sandboxu |
| `path(): ?string` | adresár aktuálneho sandboxu |
| `engine(): ?string` | `overlay` v sandboxe |
| `table_prefix(): ?string` | prefix tabuliek sandboxu, napríklad `wp_b65338d_` |
| `url(): ?string` | URL sandboxu; prekrývajúce sandboxy zdieľajú hostiteľské URL |
| `exit_url(): string` | hostiteľské URL |
| `is_email_disabled(): bool` | `true`, ak je pre požiadavku blokovaná odchádzajúca pošta |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | nainštalovaná verzia Rudel |
| `cli_command(): string` | koreňový príkaz WP-CLI, `rudel`, pokiaľ nie je nastavené `RUDEL_CLI_COMMAND` |

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

Vráti všetky vyššie uvedené údaje v jednom poli:

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

Vráti rovnaký súhrn prostredia behu ako `wp rudel status` vo forme poľa: stav inicializácie, aktuálny sandbox, adresár a počet sandboxov, hodnoty `rudel_config` a informáciu, či je automatizácia naplánovaná.

## Záznamy sandboxov

Sandboxy sa vracajú ako objekty `Rudel\Environment`. Medzi užitočné vlastnosti iba na čítanie patria `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` a `clone_source`. Medzi metódy patria `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` a `to_array()`.

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

Vráti každý sandbox ako objekt `Environment` v poli. Neprijíma žiadne filtre.

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

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

Načíta sandbox podľa ID alebo vráti `null`.

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

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

Vráti adresár, v ktorom sa nachádzajú adresáre sandboxov.

## Životný cyklus

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

Vytvorí sandbox a vráti ho. ID sa vytvorí z názvu a štyroch hexadecimálnych znakov.

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

Možnosti:

| Kľúč | Význam |
|-----|---------|
| `theme` | slug témy, ktorá sa skopíruje do sandboxu; predvolene sa použije aktívna téma hostiteľa |
| `clone_from` | ID existujúceho sandboxu, ktorý sa naklonuje namiesto hostiteľa |
| `owner`, `purpose` | metadáta vo voľnom texte |
| `labels` | pole alebo reťazec hodnôt oddelených čiarkami |
| `protected` | `true` na vylúčenie sandboxu z čistenia |
| `ttl_days` | platnosť od času vytvorenia |
| `expires_at` | explicitná časová značka vypršania platnosti |
| `template` | označenie uložené v zázname; nenačíta uloženú šablónu |
| `site_options` | názvy možností a skalárne hodnoty zapísané do tabuľky možností sandboxu |
| `skip_limits` | `true` na obídenie `max_sandboxes` a `max_disk_mb` |

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

Vytvorí sandbox a potom doň naklonuje `$remote_url`. Prijíma možnosti `create()` a navyše `name` (predvolene názov úložiska) a `type` (`theme` alebo `plugin`). Vráti `[ 'environment' => Environment, 'git' => [...] ]`. Neúspešné klonovanie nezruší vytvorenie sandboxu; chyba sa vráti v `git.error`. Pozrite si [Git](https://rudel.inline0.dev/sk/docs/features/git).

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

Aktualizuje metadáta životného cyklu a vráti obnovený sandbox. Medzi prijímané kľúče patria `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relatívne k aktuálnemu času), `expires_at`, `clear_expiry`, `name` a `site_options`.

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

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

Odstráni tabuľky sandboxu, jeho adresár a prepojené pracovné stromy a vymaže jeho záznam. Ak ID neexistuje, vráti `false`. Kontrola ochrany sa nevykonáva: odstránia sa aj chránené sandboxy.

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

Uplatní pravidlá vypršania platnosti, veku a nečinnosti. Možnosti: `dry_run` (bool), `max_age_days` a `max_idle_days` (prepíšu `rudel_config`, ak sú nenulové). Vráti `removed`, `skipped`, `errors` a `reasons` (ID na `expired`, `age`, `idle` alebo `protected`). Pozrite si [Čistenie](https://rudel.inline0.dev/sk/docs/features/cleanup).

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

Odstráni sandboxy, ktorých prepojené vetvy pracovných stromov Git boli zlúčené do predvolenej vetvy úložiska. Možnosť: `dry_run`.

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

Zaznamená aktivitu (`last_used_at`) aktuálneho sandboxu. Rudel sa volá pri každej požiadavke sandboxu.

## Denníky

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

Vráti posledné riadky denníka sandboxu `debug.log` ako `path`, `exists`, `empty`, `total_lines` a `lines`.

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

Vyprázdni denník sandboxu `debug.log` a vráti `path`, `existed` a `cleared`.

## Snímky stavu

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

Vytvorí snímku stavu a vráti jej metadáta (`name`, `created_at`, `sandbox_id`).

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

Obnoví snímku stavu. Pri predvolenom nastavení `auto_snapshot_before_restore` najprv Rudel uloží snímku stavu `pre-restore-...`.

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

Zobrazí metadáta snímok stavu, od najnovšej. Pozrite si [Snímky stavu](https://rudel.inline0.dev/sk/docs/features/snapshots).

## Šablóny

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

Uložené šablóny sú iba kópie súborov. Žiadne API ani príkaz z nich nevytvára sandbox. Pozrite si [Šablóny](https://rudel.inline0.dev/sk/docs/features/templates).

## Git

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

Potvrdí zmeny a odošle checkout v adresári sandboxu do vetvy `rudel/{id}`. `$remote_url` a `$subdir` štandardne preberajú hodnoty uložené v sandboxe. Vráti SHA commitu alebo `null`, ak sa nič nezmenilo.

## Automatizácia

- `Rudel::run_automation(): array` teraz spustí naplánované automatizačné úlohy.
- `Rudel::run_scheduled_cleanup(): array` vykoná to isté.

Pozrite si časť [Automatizácia](https://rudel.inline0.dev/sk/docs/features/automation).

## Hooky a katalóg príkazov

- `Rudel::hooks(): array` vráti zdokumentovaný katalóg hookov usporiadaný podľa názvu hooku. Pozrite si časť [Hooky](https://rudel.inline0.dev/sk/docs/features/hooks).
- `Rudel::cli_command_map(): array` vráti serializovateľný opis každého príkazu `wp rudel` a metódy PHP, ktorá je za ním.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` zmení jeden parsovaný príkaz na plán vykonania bez toho, aby ho spustil.

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

Väčšina plánov používa transport `php`. `logs --follow` sa vyhodnotí ako plán `shell` spustený cez `tail -f`.

## Samostatná inicializácia

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

Nasmeruje fasádu na priame pripojenie MySQL na použitie mimo WordPress. `$context` prijíma `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` vytvorí tabuľky Rudel pre aktívne pripojenie.
- `Rudel::reset(): void` vymaže samostatné pripojenie a údaje vo vyrovnávacej pamäti.