API

以 Markdown 格式查看在 GitHub 上编辑文档位置 7a44bd6

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。请参阅独立使用。

运行时上下文

这些方法描述当前请求。在沙盒外，它们会返回 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。

`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）。请参阅清理。

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

按时间倒序列出快照元数据。请参阅快照。

模板

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

已保存的模板只是文件副本。没有任何 API 或命令会根据模板创建沙盒。请参阅模板。

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 执行相同操作。

请参阅自动化。

钩子和命令目录

Rudel::hooks(): array 返回按钩子名称索引的文档钩子目录。请参阅钩子。
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 清除独立连接和缓存状态。