# 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/ko/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` | `RUDEL_CLI_COMMAND`이 설정되지 않은 경우 WP-CLI 루트 명령 `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는 이름에 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/ko/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`

샌드박스 테이블을 삭제하고, 디렉터리와 연결된 worktree를 제거한 다음 레코드를 삭제합니다. ID가 존재하지 않으면 `false`을 반환합니다. 보호 여부는 확인하지 않으므로 보호된 샌드박스도 삭제됩니다.

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

만료, 사용 기간 및 유휴 정책을 실행합니다. 옵션: `dry_run`(bool), `max_age_days` 및 `max_idle_days`(0이 아니면 `rudel_config`을 재정의). `removed`, `skipped`, `errors` 및 `reasons`을 반환합니다(ID별 `expired`, `age`, `idle` 또는 `protected`). [정리](https://rudel.inline0.dev/ko/docs/features/cleanup)를 참고하세요.

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

연결된 Git worktree 브랜치가 저장소의 기본 브랜치에 병합된 샌드박스를 제거합니다. 옵션: `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/ko/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/ko/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/ko/docs/features/automation)를 참고하세요.

## 훅 및 명령 카탈로그

- `Rudel::hooks(): array`은 훅 이름을 키로 사용하는 문서화된 훅 카탈로그를 반환합니다. [훅](https://rudel.inline0.dev/ko/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`

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`는 독립 실행형 연결과 캐시된 상태를 지웁니다.