# API

`Rudel\Rudel` to statyczna fasada. Każda metoda na tej stronie jest publiczną metodą statyczną tej klasy.

```php
use Rudel\Rudel;

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

Metody cyklu życia, które klonują lub usuwają tabele (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), wymagają aktywnego żądania WordPress z `$wpdb`. Wywołanie ich po `Rudel::init()` poza WordPress spowoduje zgłoszenie `RuntimeException`. Zobacz [Użycie samodzielne](https://rudel.inline0.dev/pl/docs/features/standalone-use).

## Kontekst środowiska uruchomieniowego

Te metody opisują bieżące żądanie. Poza piaskownicą zwracają `false` lub `null`.

| Metoda | Zwracana wartość |
|--------|---------|
| `is_sandbox(): bool` | `true`, jeśli bieżące żądanie działa w piaskownicy |
| `id(): ?string` | identyfikator bieżącej piaskownicy |
| `path(): ?string` | katalog bieżącej piaskownicy |
| `engine(): ?string` | `overlay` w piaskownicy |
| `table_prefix(): ?string` | prefiks tabel piaskownicy, na przykład `wp_b65338d_` |
| `url(): ?string` | URL piaskownicy; piaskownice nakładkowe współdzielą URL hosta |
| `exit_url(): string` | URL hosta |
| `is_email_disabled(): bool` | `true`, gdy poczta wychodząca jest blokowana dla żądania |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | zainstalowana wersja Rudel |
| `cli_command(): string` | główne polecenie WP-CLI, `rudel`, chyba że ustawiono `RUDEL_CLI_COMMAND` |

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

Zwraca wszystkie powyższe wartości w jednej tablicy:

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

Zwraca w postaci tablicy to samo podsumowanie środowiska uruchomieniowego co `wp rudel status`: stan inicjalizacji, bieżąca piaskownica, katalog i liczba piaskownic, wartości `rudel_config` oraz informacja, czy zaplanowano automatyzację.

## Rekordy piaskownic

Piaskownice są zwracane jako obiekty `Rudel\Environment`. Przydatne właściwości tylko do odczytu obejmują `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` i `clone_source`. Metody obejmują `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` i `to_array()`.

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

Zwraca każdą piaskownicę jako tablicę obiektów `Environment`. Nie przyjmuje filtrów.

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

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

Wczytuje piaskownicę według identyfikatora lub zwraca `null`.

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

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

Zwraca katalog zawierający katalogi piaskownic.

## Cykl życia

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

Tworzy piaskownicę i ją zwraca. Identyfikator jest generowany z nazwy i czterech znaków szesnastkowych.

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

Opcje:

| Klucz | Znaczenie |
|-----|---------|
| `theme` | identyfikator motywu do skopiowania do piaskownicy; domyślnie aktywny motyw hosta |
| `clone_from` | identyfikator istniejącej piaskownicy, która zostanie sklonowana zamiast hosta |
| `owner`, `purpose` | metadane w postaci dowolnego tekstu |
| `labels` | tablica lub ciąg znaków rozdzielonych przecinkami |
| `protected` | `true`, aby wykluczyć piaskownicę z czyszczenia |
| `ttl_days` | czas wygaśnięcia liczony od chwili utworzenia |
| `expires_at` | jawny znacznik czasu wygaśnięcia |
| `template` | etykieta zapisana w rekordzie; nie wczytuje zapisanego szablonu |
| `site_options` | nazwy opcji i wartości skalarne zapisywane w tabeli opcji piaskownicy |
| `skip_limits` | `true`, aby pominąć `max_sandboxes` i `max_disk_mb` |

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

Tworzy piaskownicę, a następnie klonuje do niej `$remote_url`. Przyjmuje opcje `create()` oraz `name` (domyślnie nazwę repozytorium) i `type` (`theme` lub `plugin`). Zwraca `[ 'environment' => Environment, 'git' => [...] ]`. Nieudane klonowanie nie powoduje wycofania utworzenia piaskownicy; błąd jest zwracany w `git.error`. Zobacz [Git](https://rudel.inline0.dev/pl/docs/features/git).

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

Aktualizuje metadane cyklu życia i zwraca odświeżoną piaskownicę. Akceptowane klucze obejmują `owner`, `labels`, `purpose`, `protected`, `ttl_days` (względem bieżącej chwili), `expires_at`, `clear_expiry`, `name` i `site_options`.

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

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

Usuwa tabele piaskownicy, jej katalog i połączone drzewa robocze, a także kasuje jej rekord. Zwraca `false`, jeśli identyfikator nie istnieje. Nie sprawdza ochrony: chronione piaskownice również zostaną zniszczone.

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

Uruchamia zasady dotyczące wygaśnięcia, wieku i bezczynności. Opcje: `dry_run` (bool), `max_age_days` i `max_idle_days` (zastępują `rudel_config`, gdy są różne od zera). Zwraca `removed`, `skipped`, `errors` i `reasons` (identyfikator do `expired`, `age`, `idle` lub `protected`). Zobacz [Czyszczenie](https://rudel.inline0.dev/pl/docs/features/cleanup).

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

Usuwa piaskownice, których gałęzie połączonych drzew roboczych Git zostały scalone z domyślną gałęzią repozytorium. Opcja: `dry_run`.

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

Rejestruje aktywność (`last_used_at`) bieżącej piaskownicy. Rudel wywołuje tę metodę przy każdym żądaniu w piaskownicy.

## Dzienniki

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

Zwraca ostatnie wiersze dziennika `debug.log` piaskownicy jako `path`, `exists`, `empty`, `total_lines` i `lines`.

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

Opróżnia dziennik `debug.log` piaskownicy i zwraca `path`, `existed` i `cleared`.

## Migawki

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

Tworzy migawkę i zwraca jej metadane (`name`, `created_at`, `sandbox_id`).

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

Przywraca migawkę. Przy domyślnym ustawieniu `auto_snapshot_before_restore` Rudel najpierw zapisuje migawkę `pre-restore-...`.

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

Wyświetla metadane migawek, zaczynając od najnowszej. Zobacz [Migawki](https://rudel.inline0.dev/pl/docs/features/snapshots).

## Szablony

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

Zapisane szablony to wyłącznie kopie plików. Żadna metoda API ani żadne polecenie nie tworzy z nich piaskownicy. Zobacz [Szablony](https://rudel.inline0.dev/pl/docs/features/templates).

## Git

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

Zatwierdza zmiany w kopii roboczej w katalogu piaskownicy i wysyła je do gałęzi `rudel/{id}`. `$remote_url` i `$subdir` domyślnie przyjmują wartości zapisane w piaskownicy. Zwraca SHA zatwierdzenia lub `null`, jeśli nic się nie zmieniło.

## Automatyzacja

- `Rudel::run_automation(): array` uruchamia teraz zaplanowane zadania automatyzacji.
- `Rudel::run_scheduled_cleanup(): array` robi to samo.

Zobacz [Automatyzacja](https://rudel.inline0.dev/pl/docs/features/automation).

## Katalog haków i poleceń

- `Rudel::hooks(): array` zwraca udokumentowany katalog haków z kluczami będącymi nazwami haków. Zobacz [Haki](https://rudel.inline0.dev/pl/docs/features/hooks).
- `Rudel::cli_command_map(): array` zwraca możliwy do serializacji opis każdego polecenia `wp rudel` i metody PHP, która za nim stoi.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` zamienia jedno sparsowane polecenie na plan wykonania, nie uruchamiając go.

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

Większość planów korzysta z transportu `php`. `logs --follow` jest rozpoznawane jako plan `shell` wykonywany przez `tail -f`.

## Inicjalizacja samodzielna

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

Kieruje fasadę do bezpośredniego połączenia MySQL, aby można jej było używać poza WordPress. `$context` przyjmuje `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` tworzy tabele Rudel dla aktywnego połączenia.
- `Rudel::reset(): void` czyści samodzielne połączenie i stan w pamięci podręcznej.