# API

`Rudel\Rudel` es una fachada estática. Todos los métodos de esta página son métodos estáticos públicos de esa clase.

```php
use Rudel\Rudel;

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

Los métodos del ciclo de vida que clonan o eliminan tablas (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) necesitan una solicitud WordPress activa con `$wpdb`. Si se llaman después de `Rudel::init()` fuera de WordPress, lanzan un `RuntimeException`. Consulte [Uso independiente](https://rudel.inline0.dev/es/docs/features/standalone-use).

## Contexto de ejecución

Estos métodos describen la solicitud actual. Fuera de un entorno aislado, devuelven `false` o `null`.

| Método | Devuelve |
|--------|---------|
| `is_sandbox(): bool` | `true` cuando la solicitud actual se ejecuta en un entorno aislado |
| `id(): ?string` | el ID del entorno aislado actual |
| `path(): ?string` | el directorio del entorno aislado actual |
| `engine(): ?string` | `overlay` dentro de un entorno aislado |
| `table_prefix(): ?string` | el prefijo de tabla del entorno aislado, por ejemplo `wp_b65338d_` |
| `url(): ?string` | el URL del entorno aislado; los entornos aislados superpuestos comparten el URL del host |
| `exit_url(): string` | el URL del host |
| `is_email_disabled(): bool` | `true` cuando se bloquea el correo saliente para la solicitud |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | la versión instalada de Rudel |
| `cli_command(): string` | el comando raíz de WP-CLI, `rudel` salvo que se establezca `RUDEL_CLI_COMMAND` |

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

Devuelve todo lo anterior en una matriz:

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

Devuelve el mismo resumen de ejecución que `wp rudel status` como matriz: estado de inicio, entorno aislado actual, directorio y cantidad de entornos aislados, los valores de `rudel_config` y si hay automatización programada.

## Registros de entornos aislados

Los entornos aislados se devuelven como objetos `Rudel\Environment`. Entre las propiedades útiles de solo lectura se incluyen `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` y `clone_source`. Los métodos incluyen `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` y `to_array()`.

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

Devuelve todos los entornos aislados como una matriz de objetos `Environment`. No admite filtros.

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

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

Carga un entorno aislado por ID o devuelve `null`.

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

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

Devuelve el directorio que contiene los directorios de los entornos aislados.

## Ciclo de vida

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

Crea un entorno aislado y lo devuelve. El ID se genera a partir del nombre y cuatro caracteres hexadecimales.

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

Opciones:

| Clave | Significado |
|-----|---------|
| `theme` | slug del tema que se copiará al entorno aislado; de forma predeterminada, se usa el tema activo del host |
| `clone_from` | ID de un entorno aislado existente que se clonará en lugar del host |
| `owner`, `purpose` | metadatos de texto libre |
| `labels` | matriz o cadena separada por comas |
| `protected` | `true` para excluir el entorno aislado de la limpieza |
| `ttl_days` | vencimiento relativo al momento de creación |
| `expires_at` | marca de tiempo de vencimiento explícita |
| `template` | etiqueta guardada en el registro; no carga una plantilla guardada |
| `site_options` | nombres de opciones y valores escalares que se escriben en la tabla de opciones del entorno aislado |
| `skip_limits` | `true` para omitir `max_sandboxes` y `max_disk_mb` |

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

Crea un entorno aislado y luego clona `$remote_url` en él. Acepta las opciones `create()`, además de `name` (el nombre del repositorio de forma predeterminada) y `type` (`theme` o `plugin`). Devuelve `[ 'environment' => Environment, 'git' => [...] ]`. Si la clonación falla, el entorno aislado no se revierte; el error se devuelve en `git.error`. Consulte [Git](https://rudel.inline0.dev/es/docs/features/git).

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

Actualiza los metadatos del ciclo de vida y devuelve el entorno aislado actualizado. Entre las claves aceptadas se incluyen `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relativo al momento actual), `expires_at`, `clear_expiry`, `name` y `site_options`.

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

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

Elimina las tablas del entorno aislado, borra su directorio y los árboles de trabajo vinculados, y elimina su registro. Devuelve `false` si el ID no existe. No comprueba si está protegido: también se destruyen los entornos aislados protegidos.

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

Aplica la política de vencimiento, antigüedad e inactividad. Opciones: `dry_run` (bool), `max_age_days` y `max_idle_days` (anulan `rudel_config` si no son cero). Devuelve `removed`, `skipped`, `errors` y `reasons` (ID a `expired`, `age`, `idle` o `protected`). Consulte [Limpieza](https://rudel.inline0.dev/es/docs/features/cleanup).

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

Elimina los entornos aislados cuyas ramas de árboles de trabajo de Git vinculados se hayan fusionado con la rama predeterminada del repositorio. Opción: `dry_run`.

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

Registra la actividad (`last_used_at`) del entorno aislado actual. Rudel lo llama en cada solicitud del entorno aislado.

## Registros

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

Devuelve las últimas líneas del registro `debug.log` del entorno aislado como `path`, `exists`, `empty`, `total_lines` y `lines`.

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

Vacía el registro `debug.log` del entorno aislado y devuelve `path`, `existed` y `cleared`.

## Instantáneas

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

Crea una instantánea y devuelve sus metadatos (`name`, `created_at`, `sandbox_id`).

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

Restaura una instantánea. Con la opción predeterminada `auto_snapshot_before_restore`, Rudel guarda primero una instantánea `pre-restore-...`.

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

Enumera los metadatos de las instantáneas, empezando por la más reciente. Consulte [Instantáneas](https://rudel.inline0.dev/es/docs/features/snapshots).

## Plantillas

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

Las plantillas guardadas son solo copias de archivos. Ningún API ni comando crea un entorno aislado a partir de ellas. Consulte [Plantillas](https://rudel.inline0.dev/es/docs/features/templates).

## Git

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

Confirma y publica en la rama `rudel/{id}` una copia de trabajo dentro del directorio del entorno aislado. `$remote_url` y `$subdir` usan de forma predeterminada los valores guardados en el entorno aislado. Devuelve el SHA de la confirmación o `null` si no hubo cambios.

## Automatización

- `Rudel::run_automation(): array` ejecuta ahora las tareas de automatización programadas.
- `Rudel::run_scheduled_cleanup(): array` hace lo mismo.

Consulte [Automatización](https://rudel.inline0.dev/es/docs/features/automation).

## Ganchos y catálogo de comandos

- `Rudel::hooks(): array` devuelve el catálogo documentado de ganchos, organizado por nombre de gancho. Consulte [Ganchos](https://rudel.inline0.dev/es/docs/features/hooks).
- `Rudel::cli_command_map(): array` devuelve una descripción serializable de cada comando `wp rudel` y del método PHP correspondiente.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` convierte un comando analizado en un plan de ejecución sin ejecutarlo.

```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 mayoría de los planes usan el transporte `php`. `logs --follow` se convierte en un plan `shell` que se ejecuta `tail -f`.

## Inicialización independiente

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

Dirige la fachada a una conexión directa MySQL para usarla fuera de WordPress. `$context` acepta `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 las tablas Rudel para la conexión activa.
- `Rudel::reset(): void` borra la conexión independiente y el estado en caché.