# API

`Rudel\Rudel` adalah facade statis. Setiap metode di halaman ini merupakan metode statis publik dari kelas tersebut.

```php
use Rudel\Rudel;

if ( Rudel::is_sandbox() ) {
    error_log( 'Running in sandbox ' . Rudel::id() );
}
```

Metode siklus hidup yang mengkloning atau menghapus tabel (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) memerlukan permintaan WordPress yang aktif dengan `$wpdb`. Metode tersebut melempar `RuntimeException` jika dipanggil setelah `Rudel::init()` di luar WordPress. Lihat [Penggunaan Mandiri](https://rudel.inline0.dev/id/docs/features/standalone-use).

## Konteks runtime

Metode ini menjelaskan permintaan saat ini. Di luar sandbox, metode tersebut mengembalikan `false` atau `null`.

| Metode | Mengembalikan |
|--------|---------|
| `is_sandbox(): bool` | `true` saat permintaan saat ini berjalan di dalam sandbox |
| `id(): ?string` | ID sandbox saat ini |
| `path(): ?string` | direktori sandbox saat ini |
| `engine(): ?string` | `overlay` di dalam sandbox |
| `table_prefix(): ?string` | prefiks tabel sandbox, misalnya `wp_b65338d_` |
| `url(): ?string` | URL sandbox; sandbox overlay berbagi URL host |
| `exit_url(): string` | URL host |
| `is_email_disabled(): bool` | `true` saat email keluar diblokir untuk permintaan tersebut |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | versi Rudel yang terpasang |
| `cli_command(): string` | perintah root WP-CLI, kecuali jika `RUDEL_CLI_COMMAND` ditetapkan sebagai `rudel` |

### `Rudel::context(): array`

Mengembalikan semua hal di atas dalam satu 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`

Mengembalikan ringkasan runtime yang sama dengan `wp rudel status` dalam bentuk array: status bootstrap, sandbox saat ini, direktori dan jumlah sandbox, nilai `rudel_config` serta apakah otomasi dijadwalkan.

## Catatan sandbox

Sandbox dikembalikan sebagai objek `Rudel\Environment`. Properti hanya-baca yang berguna mencakup `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix`, dan `clone_source`. Metodenya mencakup `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()`, dan `to_array()`.

### `Rudel::all(): array`

Mengembalikan setiap sandbox sebagai array objek `Environment`. Tidak ada filter yang digunakan.

```php
foreach ( Rudel::all() as $sandbox ) {
    echo $sandbox->id . ' ' . $sandbox->status . "\n";
}
```

### `Rudel::get( string $id ): ?Environment`

Memuat satu sandbox berdasarkan ID, atau mengembalikan `null`.

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

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

Mengembalikan direktori tempat direktori sandbox disimpan.

## Siklus hidup

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

Membuat sandbox dan mengembalikannya. ID dibuat dari nama ditambah empat karakter heksadesimal.

```php
$sandbox = Rudel::create( 'alpha', [
    'theme'    => 'twentytwentyfour',
    'owner'    => 'dennis',
    'labels'   => [ 'qa', 'agent' ],
    'ttl_days' => 7,
] );
```

Opsi:

| Kunci | Arti |
|-----|---------|
| `theme` | slug tema yang akan disalin ke sandbox; secara default menggunakan tema aktif host |
| `clone_from` | ID sandbox yang sudah ada untuk dikloning sebagai pengganti host |
| `owner`, `purpose` | metadata teks bebas |
| `labels` | array atau string yang dipisahkan koma |
| `protected` | `true` untuk mengecualikan sandbox dari pembersihan |
| `ttl_days` | masa berlaku relatif terhadap waktu pembuatan |
| `expires_at` | stempel waktu kedaluwarsa eksplisit |
| `template` | label yang disimpan pada catatan; label ini tidak memuat templat tersimpan |
| `site_options` | nama opsi dan nilai skalar yang ditulis ke tabel opsi sandbox |
| `skip_limits` | `true` untuk melewati `max_sandboxes` dan `max_disk_mb` |

### `Rudel::create_from_git( string $remote_url, array $options = [] ): array`

Membuat sandbox, lalu mengkloning `$remote_url` ke dalamnya. Menerima opsi `create()` ditambah `name` (secara default nama repositori) dan `type` (`theme` atau `plugin`). Mengembalikan `[ 'environment' => Environment, 'git' => [...] ]`. Kegagalan kloning tidak membatalkan pembuatan sandbox; kesalahan dikembalikan dalam `git.error`. Lihat [Git](https://rudel.inline0.dev/id/docs/features/git).

### `Rudel::update( string $id, array $changes ): Environment`

Memperbarui metadata siklus hidup dan mengembalikan sandbox yang telah diperbarui. Kunci yang diterima mencakup `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relatif terhadap waktu sekarang), `expires_at`, `clear_expiry`, `name`, dan `site_options`.

```php
Rudel::update( 'alpha-3be7', [ 'protected' => true, 'ttl_days' => 3 ] );
```

### `Rudel::destroy( string $id ): bool`

Menghapus tabel sandbox, direktori dan worktree tertautnya, lalu menghapus catatannya. Mengembalikan `false` jika ID tidak ada. Perlindungan tidak diperiksa: sandbox yang dilindungi juga akan dihancurkan.

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

Menjalankan kebijakan kedaluwarsa, usia, dan tidak aktif. Opsi: `dry_run` (bool), `max_age_days`, dan `max_idle_days` (mengganti `rudel_config` jika bukan nol). Mengembalikan `removed`, `skipped`, `errors`, dan `reasons` (ID ke `expired`, `age`, `idle`, atau `protected`). Lihat [Pembersihan](https://rudel.inline0.dev/id/docs/features/cleanup).

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

Menghapus sandbox yang cabang worktree Git tertautnya telah digabung ke cabang default repositori. Opsi: `dry_run`.

### `Rudel::touch_current_environment(): void`

Mencatat aktivitas (`last_used_at`) untuk sandbox saat ini. Rudel memanggilnya pada setiap permintaan sandbox.

## Log

### `Rudel::read_log( string $id, int $lines = 50 ): array`

Mengembalikan baris terakhir `debug.log` sandbox sebagai `path`, `exists`, `empty`, `total_lines`, dan `lines`.

### `Rudel::clear_log( string $id ): array`

Mengosongkan `debug.log` sandbox dan mengembalikan `path`, `existed`, dan `cleared`.

## Snapshot

### `Rudel::snapshot( string $id, string $name ): array`

Membuat snapshot dan mengembalikan metadatanya (`name`, `created_at`, `sandbox_id`).

### `Rudel::restore( string $id, string $name ): void`

Memulihkan snapshot. Dengan pengaturan default `auto_snapshot_before_restore`, Rudel terlebih dahulu menyimpan snapshot `pre-restore-...`.

### `Rudel::snapshots( string $id ): array`

Mencantumkan metadata snapshot, dari yang terbaru. Lihat [Snapshot](https://rudel.inline0.dev/id/docs/features/snapshots).

## Templat

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

Templat tersimpan hanyalah salinan berkas. Tidak ada API atau perintah yang membuat sandbox dari templat tersebut. Lihat [Templat](https://rudel.inline0.dev/id/docs/features/templates).

## Git

### `Rudel::push( string $id, string $remote_url = '', string $message = 'Update from Rudel', string $subdir = '' ): ?string`

Melakukan commit dan push checkout di dalam direktori sandbox ke cabang `rudel/{id}`. Secara default, `$remote_url` dan `$subdir` menggunakan nilai yang tersimpan di sandbox. Mengembalikan SHA commit, atau `null` jika tidak ada perubahan.

## Otomasi

- `Rudel::run_automation(): array` menjalankan tugas otomasi terjadwal sekarang.
- `Rudel::run_scheduled_cleanup(): array` melakukan hal yang sama.

Lihat [Otomasi](https://rudel.inline0.dev/id/docs/features/automation).

## Hook dan katalog perintah

- `Rudel::hooks(): array` mengembalikan katalog hook yang didokumentasikan, berdasarkan nama hook. Lihat [Hook](https://rudel.inline0.dev/id/docs/features/hooks).
- `Rudel::cli_command_map(): array` mengembalikan deskripsi serialisasi setiap perintah `wp rudel` dan metode PHP yang mendasarinya.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` mengubah satu perintah yang diurai menjadi rencana eksekusi tanpa menjalankannya.

```php
$plan = Rudel::resolve_cli_command( 'wp rudel destroy', [ 'alpha-3be7' ] );
// $plan['callable']           => 'Rudel\Rudel::destroy'
// $plan['arguments']          => [ 'alpha-3be7' ]
// $plan['needs_confirmation'] => true
```

Sebagian besar rencana menggunakan transport `php`. `logs --follow` menghasilkan rencana `shell` yang berjalan `tail -f`.

## Inisialisasi mandiri

### `Rudel::init( Connection $connection, array $context = [] ): void`

Menghubungkan facade ke koneksi langsung MySQL untuk digunakan di luar WordPress. `$context` menerima `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` membuat tabel Rudel untuk koneksi aktif.
- `Rudel::reset(): void` menghapus koneksi mandiri dan status cache.