# 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()`）需要一个带有 `$wpdb` 的有效 WordPress 请求。在 WordPress 外通过 `Rudel::init()` 初始化后调用这些方法时，它们会抛出 `RuntimeException`。请参阅 [独立使用](https://rudel.inline0.dev/zh/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` 相同的运行时摘要：引导状态、当前沙盒、沙盒目录和数量、`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/zh/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`（布尔值）、`max_age_days` 和 `max_idle_days`（非零时覆盖 `rudel_config`）。返回 `removed`、`skipped`、`errors` 和 `reasons`（从 ID 映射到 `expired`、`age`、`idle` 或 `protected`）。请参阅 [清理](https://rudel.inline0.dev/zh/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`

以 `path`、`exists`、`empty`、`total_lines` 和 `lines` 的形式返回沙盒 `debug.log` 的最后几行。

### `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/zh/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/zh/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/zh/docs/features/automation)。

## 钩子和命令目录

- `Rudel::hooks(): array` 返回按钩子名称索引的文档钩子目录。请参阅 [钩子](https://rudel.inline0.dev/zh/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` 会解析为一个在 `tail -f` 上运行的 `shell` 计划。

## 独立初始化

### `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` 清除独立连接和缓存状态。