# API

`Rudel\Rudel`は静的ファサードです。このページの各メソッドは、そのクラスのpublic staticメソッドです。

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

上記すべてを1つの配列で返します。

```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でサンドボックスを1つ読み込みます。見つからない場合は`null`を返します。

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

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

サンドボックスのディレクトリを格納するディレクトリを返します。

## ライフサイクル

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

サンドボックスを作成して返します。IDは名前に4桁の16進数文字を加えて生成されます。

```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` | `max_sandboxes`と`max_disk_mb`をバイパスする`true` |

### `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/ja/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/ja/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/ja/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/ja/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/ja/docs/features/automation)を参照してください。

## フックとコマンド一覧

- `Rudel::hooks(): array`はフック名をキーとする、ドキュメント化されたフック一覧を返します。[フック](https://rudel.inline0.dev/ja/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`

WordPress外で使うため、ファサードを直接MySQL接続に向けます。`$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`は単独接続とキャッシュ状態をクリアします。