# API

`Rudel\Rudel` — це статичний фасад. Кожен метод на цій сторінці є публічним статичним методом цього класу.

```php
use Rudel\Rudel;

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

Методи життєвого циклу, що клонують або видаляють таблиці (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`), потребують активного запиту WordPress з `$wpdb`. Якщо викликати їх після `Rudel::init()` поза межами WordPress, вони спричинять `RuntimeException`. Див. [Автономне використання](https://rudel.inline0.dev/uk/docs/features/standalone-use).

## Контекст виконання

Ці методи описують поточний запит. Поза пісочницею вони повертають `false` або `null`.

| Метод | Повертає |
|--------|---------|
| `is_sandbox(): bool` | `true`, коли поточний запит виконується в ізольованому середовищі |
| `id(): ?string` | ідентифікатор поточного ізольованого середовища |
| `path(): ?string` | каталог поточного ізольованого середовища |
| `engine(): ?string` | `overlay` в ізольованому середовищі |
| `table_prefix(): ?string` | префікс таблиць ізольованого середовища, наприклад `wp_b65338d_` |
| `url(): ?string` | URL ізольованого середовища; накладені ізольовані середовища використовують спільний із хостом URL |
| `exit_url(): string` | URL хоста |
| `is_email_disabled(): bool` | `true`, коли для запиту заблоковано вихідну пошту |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | версія встановленого Rudel |
| `cli_command(): string` | коренева команда WP-CLI, `rudel`, якщо задано `RUDEL_CLI_COMMAND` |

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

Повертає все перелічене вище одним масивом:

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

Повертає те саме зведення середовища виконання, що й `wp rudel status`, у вигляді масиву: стан початкового налаштування, поточна пісочниця, каталог і кількість пісочниць, значення `rudel_config` і відомості про заплановану автоматизацію.

## Записи пісочниць

Пісочниці повертаються як об’єкти `Rudel\Environment`. До корисних властивостей лише для читання належать `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` і `clone_source`. Методи включають `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` і `to_array()`.

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

Повертає кожну пісочницю як масив об’єктів `Environment`. Фільтри не приймаються.

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

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

Завантажує одну пісочницю за ID або повертає `null`.

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

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

Повертає каталог, у якому зберігаються каталоги пісочниць.

## Життєвий цикл

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

Створює пісочницю та повертає її. ID формується з назви та чотирьох шістнадцяткових символів.

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

Параметри:

| Ключ | Значення |
|-----|---------|
| `theme` | ідентифікатор теми для копіювання в пісочницю; типово — активна тема хоста |
| `clone_from` | ID наявної пісочниці, яку потрібно клонувати замість хоста |
| `owner`, `purpose` | довільні текстові метадані |
| `labels` | масив або рядок зі значеннями, розділеними комами |
| `protected` | `true`, щоб виключити пісочницю з очищення |
| `ttl_days` | строк дії відносно часу створення |
| `expires_at` | явна часова позначка завершення строку дії |
| `template` | мітка в записі; вона не завантажує збережений шаблон |
| `site_options` | назви параметрів і скалярні значення для запису в таблицю параметрів пісочниці |
| `skip_limits` | `true`, щоб обійти `max_sandboxes` і `max_disk_mb` |

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

Створює пісочницю, а потім клонує в неї `$remote_url`. Приймає параметри `create()`, а також `name` (типово — назва репозиторію) і `type` (`theme` або `plugin`). Повертає `[ 'environment' => Environment, 'git' => [...] ]`. Помилка клонування не скасовує створення пісочниці; помилку повернуто в `git.error`. Див. [Git](https://rudel.inline0.dev/uk/docs/features/git).

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

Оновлює метадані життєвого циклу та повертає оновлену пісочницю. Серед прийнятих ключів: `owner`, `labels`, `purpose`, `protected`, `ttl_days` (відносно поточного часу), `expires_at`, `clear_expiry`, `name` і `site_options`.

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

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

Видаляє таблиці пісочниці, її каталог і пов’язані робочі дерева та запис. Якщо такого ID немає, повертає `false`. Перевірка захисту не виконується: захищені пісочниці також буде видалено.

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

Застосовує політику завершення строку дії, віку й бездіяльності. Параметри: `dry_run` (bool), `max_age_days` і `max_idle_days` (перевизначають `rudel_config`, якщо значення не дорівнює нулю). Повертає `removed`, `skipped`, `errors` і `reasons` (ID зі значенням `expired`, `age`, `idle` або `protected`). Див. [Очищення](https://rudel.inline0.dev/uk/docs/features/cleanup).

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

Видаляє пісочниці, гілки робочих дерев Git яких об’єднано з типовою гілкою репозиторію. Параметр: `dry_run`.

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

Записує дію (`last_used_at`) для поточної пісочниці. Rudel викликає цей метод для кожного запиту в пісочниці.

## Журнали

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

Повертає останні рядки `debug.log` пісочниці як `path`, `exists`, `empty`, `total_lines` і `lines`.

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

Очищає `debug.log` пісочниці та повертає `path`, `existed` і `cleared`.

## Знімки стану

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

Створює знімок і повертає його метадані (`name`, `created_at`, `sandbox_id`).

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

Відновлює знімок. За типового параметра `auto_snapshot_before_restore` Rudel спершу зберігає знімок `pre-restore-...`.

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

Перелічує метадані знімків, починаючи з найновіших. Див. розділ [Знімки стану](https://rudel.inline0.dev/uk/docs/features/snapshots).

## Шаблони

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

Збережені шаблони — це лише копії файлів. Жоден API чи команда не створює з них пісочницю. Див. розділ [Шаблони](https://rudel.inline0.dev/uk/docs/features/templates).

## Git

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

Фіксує зміни та надсилає вміст робочої копії з каталогу пісочниці до гілки `rudel/{id}`. Типово для `$remote_url` і `$subdir` використовуються значення пісочниці. Повертає SHA коміту або `null`, якщо змін немає.

## Автоматизація

- `Rudel::run_automation(): array` запускає заплановані завдання автоматизації.
- `Rudel::run_scheduled_cleanup(): array` робить те саме.

Див. розділ [Автоматизація](https://rudel.inline0.dev/uk/docs/features/automation).

## Хуки та каталог команд

- `Rudel::hooks(): array` повертає задокументований каталог хуків, упорядкований за назвами хуків. Див. розділ [Хуки](https://rudel.inline0.dev/uk/docs/features/hooks).
- `Rudel::cli_command_map(): array` повертає серіалізований опис кожної команди `wp rudel` і відповідного їй методу PHP.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` перетворює одну розібрану команду на план виконання, не запускаючи її.

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

Для більшості планів використовується транспорт `php`. `logs --follow` перетворюється на план `shell`, який виконує `tail -f`.

## Автономне ініціалізування

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

Налаштовує фасад на пряме з’єднання MySQL для використання поза межами WordPress. `$context` приймає `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` створює таблиці Rudel для активного з’єднання.
- `Rudel::reset(): void` очищує автономне з’єднання та кешований стан.