# API

`Rudel\Rudel` è una facciata statica. Ogni metodo descritto in questa pagina è un metodo statico pubblico di quella classe.

```php
use Rudel\Rudel;

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

I metodi del ciclo di vita che clonano o eliminano tabelle (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) richiedono una richiesta WordPress attiva con `$wpdb`. Se chiamati dopo `Rudel::init()` al di fuori di WordPress, generano un'eccezione `RuntimeException`. Consultate [Uso autonomo](https://rudel.inline0.dev/it/docs/features/standalone-use).

## Contesto di esecuzione

Questi metodi descrivono la richiesta corrente. Al di fuori di una sandbox restituiscono `false` o `null`.

| Metodo | Restituisce |
|--------|---------|
| `is_sandbox(): bool` | `true` quando la richiesta corrente viene eseguita all'interno di una sandbox |
| `id(): ?string` | l'ID della sandbox corrente |
| `path(): ?string` | la directory della sandbox corrente |
| `engine(): ?string` | `overlay` all'interno di una sandbox |
| `table_prefix(): ?string` | il prefisso delle tabelle della sandbox, ad esempio `wp_b65338d_` |
| `url(): ?string` | la sandbox URL; le sandbox overlay condividono URL dell'host |
| `exit_url(): string` | URL dell'host |
| `is_email_disabled(): bool` | `true` quando la posta in uscita è bloccata per la richiesta |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | la versione di Rudel installata |
| `cli_command(): string` | il comando radice WP-CLI, `rudel` a meno che non sia impostato `RUDEL_CLI_COMMAND` |

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

Restituisce tutti i dati precedenti in un unico 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`

Restituisce lo stesso riepilogo del runtime di `wp rudel status` come array: stato di bootstrap, sandbox corrente, directory e numero delle sandbox, i valori di `rudel_config` e l'indicazione se l'automazione è pianificata.

## Record delle sandbox

Le sandbox vengono restituite come oggetti `Rudel\Environment`. Tra le proprietà utili di sola lettura figurano `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` e `clone_source`. I metodi includono `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` e `to_array()`.

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

Restituisce ogni sandbox come array di oggetti `Environment`. Non accetta filtri.

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

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

Carica una sandbox in base all'ID oppure restituisce `null`.

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

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

Restituisce la directory che contiene le directory delle sandbox.

## Ciclo di vita

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

Crea una sandbox e la restituisce. L'ID viene generato a partire dal nome seguito da quattro caratteri esadecimali.

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

Opzioni:

| Chiave | Significato |
|-----|---------|
| `theme` | slug del tema da copiare nella sandbox; per impostazione predefinita, il tema attivo dell'host |
| `clone_from` | ID di una sandbox esistente da clonare al posto dell'host |
| `owner`, `purpose` | metadati in testo libero |
| `labels` | array o stringa separata da virgole |
| `protected` | `true` per escludere la sandbox dalla pulizia |
| `ttl_days` | scadenza calcolata a partire dall'ora di creazione |
| `expires_at` | data e ora di scadenza esplicite |
| `template` | etichetta memorizzata nel record; non carica un modello salvato |
| `site_options` | nomi delle opzioni e valori scalari scritti nella tabella delle opzioni della sandbox |
| `skip_limits` | `true` per ignorare `max_sandboxes` e `max_disk_mb` |

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

Crea una sandbox, quindi vi clona `$remote_url`. Accetta le opzioni di `create()`, oltre a `name` (per impostazione predefinita, il nome del repository) e `type` (`theme` oppure `plugin`). Restituisce `[ 'environment' => Environment, 'git' => [...] ]`. Se la clonazione non riesce, la sandbox non viene ripristinata; l'errore è restituito in `git.error`. Vedi [ClonazioneGit](https://rudel.inline0.dev/it/docs/features/git).

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

Aggiorna i metadati del ciclo di vita e restituisce la sandbox aggiornata. Tra le chiavi accettate figurano `owner`, `labels`, `purpose`, `protected`, `ttl_days` (rispetto all'ora corrente), `expires_at`, `clear_expiry`, `name` e `site_options`.

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

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

Elimina le tabelle della sandbox, rimuove la sua directory e i worktree collegati, quindi elimina il relativo record. Restituisce `false` se l'ID non esiste. Non verifica la protezione: elimina anche le sandbox protette.

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

Applica le regole di scadenza, anzianità e inattività. Opzioni: `dry_run` (bool), `max_age_days` e `max_idle_days` (sovrascrivono `rudel_config` se diversi da zero). Restituisce `removed`, `skipped`, `errors` e `reasons` (ID associato a `expired`, `age`, `idle` o `protected`). Vedi [Pulizia](https://rudel.inline0.dev/it/docs/features/cleanup).

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

Rimuove le sandbox i cui rami dei worktree Git collegati sono stati uniti al ramo predefinito del repository. Opzione: `dry_run`.

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

Registra l'attività (`last_used_at`) per la sandbox corrente. Rudel lo richiama a ogni richiesta relativa a una sandbox.

## Log

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

Restituisce le ultime righe del file `debug.log` della sandbox come `path`, `exists`, `empty`, `total_lines` e `lines`.

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

Svuota `debug.log` della sandbox e restituisce `path`, `existed` e `cleared`.

## Snapshot

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

Crea uno snapshot e ne restituisce i metadati (`name`, `created_at`, `sandbox_id`).

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

Ripristina uno snapshot. Con l'impostazione predefinita `auto_snapshot_before_restore`, Rudel salva prima uno snapshot `pre-restore-...`.

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

Elenca i metadati degli snapshot, dal più recente. Vedi [Snapshot](https://rudel.inline0.dev/it/docs/features/snapshots).

## Modelli

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

I modelli salvati sono solo copie di file. Nessun API o comando crea una sandbox a partire da un modello. Vedi [Modelli](https://rudel.inline0.dev/it/docs/features/templates).

## Git

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

Esegue il commit e il push di un checkout all'interno della directory della sandbox sul ramo `rudel/{id}`. `$remote_url` e `$subdir` usano per impostazione predefinita i valori memorizzati nella sandbox. Restituisce lo SHA del commit oppure `null` se non è cambiato nulla.

## Automazione

- `Rudel::run_automation(): array` esegue subito le attività di automazione pianificate.
- `Rudel::run_scheduled_cleanup(): array` fa lo stesso.

Vedi [Automazione](https://rudel.inline0.dev/it/docs/features/automation).

## Hook e catalogo dei comandi

- `Rudel::hooks(): array` restituisce il catalogo documentato degli hook, organizzato per nome. Vedi [Hook](https://rudel.inline0.dev/it/docs/features/hooks).
- `Rudel::cli_command_map(): array` restituisce una descrizione serializzabile di ogni comando `wp rudel` e del metodo PHP associato.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` trasforma un comando analizzato in un piano di esecuzione senza eseguirlo.

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

La maggior parte dei piani usa il trasporto `php`. `logs --follow` corrisponde a un piano `shell` in esecuzione `tail -f`.

## Inizializzazione indipendente

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

Imposta la facciata affinché usi una connessione MySQL diretta, per l'utilizzo al di fuori di WordPress. `$context` accetta `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` crea le tabelle Rudel per la connessione attiva.
- `Rudel::reset(): void` cancella la connessione indipendente e lo stato memorizzato nella cache.