# API

`Rudel\Rudel` é uma fachada estática. Todos os métodos desta página são métodos estáticos públicos dessa classe.

```php
use Rudel\Rudel;

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

Os métodos do ciclo de vida que clonam ou removem tabelas (`create()`, `create_from_git()`, `destroy()`, `cleanup()`, `cleanup_merged()`) precisam de uma requisição WordPress ativa com `$wpdb`. Eles lançam um `RuntimeException` quando chamados após `Rudel::init()` fora de WordPress. Consulte [Uso independente](https://rudel.inline0.dev/pt/docs/features/standalone-use).

## Contexto de execução

Esses métodos descrevem a requisição atual. Fora de um sandbox, retornam `false` ou `null`.

| Método | Retorno |
|--------|---------|
| `is_sandbox(): bool` | `true` quando a solicitação atual é executada em uma sandbox |
| `id(): ?string` | o ID da sandbox atual |
| `path(): ?string` | o diretório da sandbox atual |
| `engine(): ?string` | `overlay` dentro de uma sandbox |
| `table_prefix(): ?string` | o prefixo das tabelas da sandbox, por exemplo `wp_b65338d_` |
| `url(): ?string` | o URL da sandbox; sandboxes overlay compartilham o URL do host |
| `exit_url(): string` | o URL do host |
| `is_email_disabled(): bool` | `true` quando o envio de e-mails está bloqueado para a solicitação |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | a versão instalada de Rudel |
| `cli_command(): string` | o comando raiz WP-CLI, `rudel` a menos que `RUDEL_CLI_COMMAND` esteja definido |

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

Retorna tudo o que foi listado acima em um único 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`

Retorna o mesmo resumo de execução que `wp rudel status` em um array: estado de inicialização, sandbox atual, diretório e quantidade de sandboxes, os valores de `rudel_config` e se a automação está agendada.

## Registros de sandbox

As sandboxes são retornadas como objetos `Rudel\Environment`. Entre as propriedades somente de leitura mais úteis estão `id`, `name`, `path`, `created_at`, `status`, `template`, `owner`, `labels`, `purpose`, `expires_at`, `last_used_at`, `theme_slug`, `table_prefix` e `clone_source`. Os métodos incluem `is_protected()`, `get_url()`, `get_table_prefix()`, `get_size()` e `to_array()`.

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

Retorna todas as sandboxes como um array de objetos `Environment`. Não aceita filtros.

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

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

Carrega uma sandbox pelo ID ou retorna `null`.

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

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

Retorna o diretório que contém os diretórios das sandboxes.

## Ciclo de vida

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

Cria uma sandbox e a retorna. O ID é gerado a partir do nome mais quatro caracteres hexadecimais.

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

Opções:

| Chave | Significado |
|-----|---------|
| `theme` | slug do tema a ser copiado para a sandbox; por padrão, usa o tema ativo do host |
| `clone_from` | ID de uma sandbox existente a ser clonada em vez do host |
| `owner`, `purpose` | metadados em texto livre |
| `labels` | array ou string separada por vírgulas |
| `protected` | `true` para excluir a sandbox da limpeza |
| `ttl_days` | validade relativa ao momento da criação |
| `expires_at` | data e hora explícitas de expiração |
| `template` | rótulo armazenado no registro; não carrega um modelo salvo |
| `site_options` | nomes de opções e valores escalares gravados na tabela de opções da sandbox |
| `skip_limits` | `true` para ignorar `max_sandboxes` e `max_disk_mb` |

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

Cria uma sandbox e, em seguida, clona `$remote_url` nela. Aceita as opções de `create()`, além de `name` (por padrão, o nome do repositório) e `type` (`theme` ou `plugin`). Retorna `[ 'environment' => Environment, 'git' => [...] ]`. Uma falha na clonagem não reverte a criação da sandbox; o erro é retornado em `git.error`. Consulte [Git](https://rudel.inline0.dev/pt/docs/features/git).

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

Atualiza os metadados do ciclo de vida e retorna a sandbox atualizada. Entre as chaves aceitas estão `owner`, `labels`, `purpose`, `protected`, `ttl_days` (relativo ao momento atual), `expires_at`, `clear_expiry`, `name` e `site_options`.

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

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

Remove as tabelas da sandbox, seu diretório e as árvores de trabalho vinculadas, e exclui seu registro. Retorna `false` quando o ID não existe. Não verifica a proteção: sandboxes protegidas também são destruídas.

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

Executa a política de expiração, idade e inatividade. Opções: `dry_run` (bool), `max_age_days` e `max_idle_days` (substituem `rudel_config` quando diferentes de zero). Retorna `removed`, `skipped`, `errors` e `reasons` (ID para `expired`, `age`, `idle` ou `protected`). Consulte [Limpeza](https://rudel.inline0.dev/pt/docs/features/cleanup).

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

Remove sandboxes cujas ramificações de árvore de trabalho vinculadas do Git foram incorporadas à ramificação padrão do repositório. Opção: `dry_run`.

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

Registra a atividade (`last_used_at`) da sandbox atual. Rudel chama esse método em cada solicitação da sandbox.

## Registros

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

Retorna as últimas linhas do `debug.log` da sandbox como `path`, `exists`, `empty`, `total_lines` e `lines`.

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

Esvazia o `debug.log` da sandbox e retorna `path`, `existed` e `cleared`.

## Instantâneos

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

Cria um instantâneo e retorna seus metadados (`name`, `created_at`, `sandbox_id`).

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

Restaura um instantâneo. Com a configuração padrão `auto_snapshot_before_restore`, Rudel salva primeiro um instantâneo `pre-restore-...`.

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

Lista os metadados dos instantâneos, dos mais recentes aos mais antigos. Consulte [Instantâneos](https://rudel.inline0.dev/pt/docs/features/snapshots).

## Modelos

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

Os modelos salvos são apenas cópias de arquivos. Nenhum API ou comando cria uma sandbox a partir de um deles. Consulte [Modelos](https://rudel.inline0.dev/pt/docs/features/templates).

## Git

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

Confirma e envia um checkout dentro do diretório da sandbox para a ramificação `rudel/{id}`. `$remote_url` e `$subdir` usam por padrão os valores armazenados na sandbox. Retorna o SHA do commit ou `null` quando não houve alterações.

## Automação

- `Rudel::run_automation(): array` executa agora as tarefas de automação agendadas.
- `Rudel::run_scheduled_cleanup(): array` faz o mesmo.

Consulte [Automação](https://rudel.inline0.dev/pt/docs/features/automation).

## Ganchos e catálogo de comandos

- `Rudel::hooks(): array` retorna o catálogo documentado de ganchos, organizado por nome de gancho. Consulte [Ganchos](https://rudel.inline0.dev/pt/docs/features/hooks).
- `Rudel::cli_command_map(): array` retorna uma descrição serializável de cada comando `wp rudel` e do método PHP correspondente.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` transforma um comando analisado em um plano de execução sem executá-lo.

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

A maioria dos planos usa o transporte `php`. `logs --follow` é resolvido em um plano `shell` executado em `tail -f`.

## Inicialização autônoma

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

Direciona a fachada para uma conexão direta MySQL, para uso fora de WordPress. `$context` aceita `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` cria as tabelas Rudel para a conexão ativa.
- `Rudel::reset(): void` limpa a conexão autônoma e o estado em cache.