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

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

- `Rudel::hooks(): array` връща документирания каталог на хуковете, подреден по име на хук. Вижте [Хукове](https://rudel.inline0.dev/bg/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` изчиства самостоятелната връзка и кешираното състояние.