# 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/ru/docs/features/standalone-use).

## Контекст выполнения

Эти методы описывают текущий запрос. Вне песочницы они возвращают `false` или `null`.

| Метод | Возвращает |
|--------|---------|
| `is_sandbox(): bool` | `true`, если текущий запрос выполняется в песочнице |
| `id(): ?string` | текущий ID песочницы |
| `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_CLI_COMMAND` (по умолчанию `rudel`) |

### `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`, в виде массива: состояние bootstrap, текущая песочница, каталог песочниц и их количество, значения `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/ru/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`

Удаляет таблицы песочницы, ее каталог и связанные рабочие деревья, а также запись о ней. Возвращает `false`, если такого ID нет. Проверка защиты не выполняется: защищенные песочницы тоже удаляются.

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

Применяет правила истечения срока, возраста и периода бездействия. Параметры: `dry_run` (логическое значение), `max_age_days` и `max_idle_days` (переопределяют `rudel_config`, если значение не равно нулю). Возвращает `removed`, `skipped`, `errors` и `reasons` (ID и `expired`, `age`, `idle` или `protected`). См. [Очистка](https://rudel.inline0.dev/ru/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/ru/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/ru/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/ru/docs/features/automation).

## Каталог хуков и команд

- `Rudel::hooks(): array` возвращает документированный каталог хуков с ключами по именам хуков. См. [Хуки](https://rudel.inline0.dev/ru/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`.

## Инициализация вне WordPress

### `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` сбрасывает автономное подключение и кешированное состояние.