# API

`Rudel\Rudel` on staattinen julkisivu. Jokainen tällä sivulla kuvattu metodi on kyseisen luokan julkinen staattinen metodi.

```php
use Rudel\Rudel;

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

Elinkaarimetodit, jotka kloonaavat tai poistavat tauluja (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), tarvitsevat käynnissä olevan WordPress-pyynnön, jossa on `$wpdb`. Ne heittävät `RuntimeException`-poikkeuksen, jos niitä kutsutaan kohteen `Rudel::init()` jälkeen kohteen WordPress ulkopuolella. Katso [Itsenäinen käyttö](https://rudel.inline0.dev/fi/docs/features/standalone-use).

## Ajonaikainen konteksti

Nämä metodit kuvaavat nykyistä pyyntöä. Hiekkalaatikon ulkopuolella ne palauttavat arvon `false` tai `null`.

| Metodi | Palautusarvo |
|--------|---------|
| `is_sandbox(): bool` | `true`, kun nykyinen pyyntö suoritetaan hiekkalaatikossa |
| `id(): ?string` | nykyisen hiekkalaatikon tunnus |
| `path(): ?string` | nykyisen hiekkalaatikon hakemisto |
| `engine(): ?string` | `overlay` hiekkalaatikossa |
| `table_prefix(): ?string` | hiekkalaatikon taulujen etuliite, esimerkiksi `wp_b65338d_` |
| `url(): ?string` | hiekkalaatikon URL; peitehiekkalaatikot jakavat isännän kohteen URL |
| `exit_url(): string` | isännän kohteen URL |
| `is_email_disabled(): bool` | `true`, kun lähtevien sähköpostien lähetys on estetty pyynnössä |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | asennettu Rudel-versio |
| `cli_command(): string` | kohteen WP-CLI juurikomento, `rudel`, ellei kohdetta `RUDEL_CLI_COMMAND` ole asetettu |

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

Palauttaa kaikki yllä mainitut yhdessä taulukossa:

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

Palauttaa saman ajonaikaisen yhteenvedon kuin `wp rudel status` taulukkona: käynnistystila, nykyinen hiekkalaatikko, hiekkalaatikoiden hakemisto ja määrä, kohteen `rudel_config` arvot sekä tieto siitä, onko automaatio ajastettu.

## Hiekkalaatikkotietueet

Hiekkalaatikot palautetaan `Rudel\Environment`-olioina. Hyödyllisiä vain luku -ominaisuuksia ovat `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` ja `clone_source`. Metodeihin kuuluvat `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` ja `to_array()`.

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

Palauttaa kaikki hiekkalaatikot `Environment`-olioiden taulukkona. Ei ota suodattimia.

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

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

Lataa yhden hiekkalaatikon tunnuksen perusteella tai palauttaa arvon `null`.

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

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

Palauttaa hakemiston, jossa hiekkalaatikkohakemistot sijaitsevat.

## Elinkaari

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

Luo hiekkalaatikon ja palauttaa sen. Tunnus muodostetaan nimestä ja neljästä heksadesimaalimerkistä.

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

Asetukset:

| Avain | Merkitys |
|-----|---------|
| `theme` | hiekkalaatikkoon kopioitavan teeman tunniste; oletuksena isännän aktiivinen teema |
| `clone_from` | olemassa olevan hiekkalaatikon tunnus, joka kloonataan isännän sijaan |
| `owner`, `purpose` | vapaamuotoinen metadata |
| `labels` | taulukko tai pilkuilla eroteltu merkkijono |
| `protected` | `true` hiekkalaatikon siivoamisen estämiseksi |
| `ttl_days` | vanhenemisaika luontihetkestä laskettuna |
| `expires_at` | nimenomainen vanhenemisen aikaleima |
| `template` | tietueeseen tallennettava tunniste; ei lataa tallennettua mallipohjaa |
| `site_options` | asetusten nimet ja skalaariset arvot, jotka kirjoitetaan hiekkalaatikon asetustauluun |
| `skip_limits` | `true`, jolla ohitetaan kohteet `max_sandboxes` ja `max_disk_mb` |

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

Luo hiekkalaatikon ja kloonaa sitten `$remote_url` siihen. Hyväksyy asetukset `create()` sekä `name` (oletuksena repositorion nimi) ja `type` (`theme` tai `plugin`). Palauttaa arvon `[ 'environment' => Environment, 'git' => [...] ]`. Epäonnistunut kloonaus ei peruuta hiekkalaatikon luontia; virhe palautetaan kohteessa `git.error`. Katso [Git](https://rudel.inline0.dev/fi/docs/features/git).

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

Päivittää elinkaarimetadatan ja palauttaa päivitetyn hiekkalaatikon. Hyväksyttyihin avaimiin kuuluvat `owner`, `labels`, `purpose`, `protected`, `ttl_days` (suhteessa nykyhetkeen), `expires_at`, `clear_expiry`, `name` ja `site_options`.

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

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

Poistaa hiekkalaatikon taulut, sen hakemiston ja siihen linkitetyt työpuut sekä tietueen. Palauttaa arvon `false`, jos tunnusta ei ole olemassa. Suojausta ei tarkisteta: myös suojatut hiekkalaatikot tuhotaan.

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

Suorittaa vanhenemis-, ikä- ja käyttämättömyyskäytännön. Asetukset: `dry_run` (bool), `max_age_days` ja `max_idle_days` (ohittavat kohteen `rudel_config`, kun arvo ei ole nolla). Palauttaa arvot `removed`, `skipped`, `errors` ja `reasons` (tunnus ja jokin arvoista `expired`, `age`, `idle` tai `protected`). Katso [Siivous](https://rudel.inline0.dev/fi/docs/features/cleanup).

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

Poistaa hiekkalaatikot, joiden linkitettyjen Git-työpuiden haarat on yhdistetty repositorion oletushaaraan. Asetus: `dry_run`.

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

Kirjaa nykyisen hiekkalaatikon toiminnan (`last_used_at`). Rudel kutsuu sitä jokaisella hiekkalaatikkopyynnöllä.

## Lokit

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

Palauttaa hiekkalaatikon `debug.log`-tiedoston viimeiset rivit muodossa `path`, `exists`, `empty`, `total_lines` ja `lines`.

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

Tyhjentää hiekkalaatikon `debug.log`-tiedoston ja palauttaa arvot `path`, `existed` ja `cleared`.

## Tilannevedokset

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

Luo tilannevedoksen ja palauttaa sen metatiedot (`name`, `created_at`, `sandbox_id`).

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

Palauttaa tilannevedoksen. Oletusasetuksella `auto_snapshot_before_restore` Rudel tallentaa ensin `pre-restore-...`-tilannevedoksen.

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

Luettelee tilannevedosten metatiedot uusimmasta vanhimpaan. Katso [Tilannevedokset](https://rudel.inline0.dev/fi/docs/features/snapshots).

## Mallipohjat

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

Tallennetut mallipohjat ovat vain tiedostokopioita. Mikään API tai komento ei luo hiekkalaatikkoa niiden pohjalta. Katso [Mallipohjat](https://rudel.inline0.dev/fi/docs/features/templates).

## Git

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

Vahvistaa hiekkalaatikon hakemiston sisällä olevan työkopion muutokset ja työntää ne haaraan `rudel/{id}`. `$remote_url` ja `$subdir` käyttävät oletuksena hiekkalaatikkoon tallennettuja arvoja. Palauttaa commit SHA -tunnisteen tai arvon `null`, jos muutoksia ei ole.

## Automaatio

- `Rudel::run_automation(): array` suorittaa ajastetut automaatiotehtävät nyt.
- `Rudel::run_scheduled_cleanup(): array` tekee saman.

Katso [Automaatio](https://rudel.inline0.dev/fi/docs/features/automation).

## Koukut ja komentoluettelo

- `Rudel::hooks(): array` palauttaa dokumentoidun hook-luettelon hook-nimen mukaan avaimella. Katso [Hookit](https://rudel.inline0.dev/fi/docs/features/hooks).
- `Rudel::cli_command_map(): array` palauttaa sarjoitettavan kuvauksen jokaisesta `wp rudel`-komennosta ja sen taustalla olevasta PHP-metodista.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` muuntaa jäsennetyn komennon suoritusohjeeksi suorittamatta sitä.

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

Useimmat suoritusohjeet käyttävät siirtotapaa `php`. `logs --follow` palauttaa kohteessa `tail -f` suoritettavan `shell`-ohjeen.

## Itsenäinen alustus

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

Ohjaa julkisivun käyttämään suoraa MySQL-yhteyttä kohteen WordPress ulkopuolella. `$context` hyväksyy arvon `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` luo Rudel-taulut aktiiviselle yhteydelle.
- `Rudel::reset(): void` tyhjentää itsenäisen yhteyden ja välimuistissa olevan tilan.