
# Cron

El sistema cron te permite definir tareas programadas que se ejecutan en segundo plano a intervalos periódicos. Añade un archivo `cron.php` al directorio de bloques y Blockstudio registra los trabajos con WordPress Cron y gestiona su ciclo de vida. Las instalaciones del plugin independiente limpian sus trabajos al desactivarse. Las instalaciones de Composer incluidas en un tema u otro plugin necesitan que el host se encargue de la limpieza o que ejecute `wp bs teardown` antes de desactivarse, cambiarse o eliminarse.

Esta es la última pieza del patrón de bloques full-stack: tu bloque puede tener un
UI (`index.twig`), lógica del servidor (`rpc.php`), datos persistentes (`db.php`) y,
ahora, procesamiento en segundo plano (`cron.php`).

## Cómo funciona

1. Creas `cron.php` en el directorio de bloques
2. Devuelve una matriz asociativa de trabajos con nombre
3. En cada carga de página, Blockstudio comprueba si los trabajos están programados
4. Los programas que faltan se registran con `wp_schedule_event()`
5. WordPress Cron ejecuta las devoluciones de llamada en el intervalo definido
6. Al desactivar el plugin independiente Blockstudio, se cancelan todos los eventos Blockstudio cron; las instalaciones incluidas en paquetes usan las rutas de limpieza que se indican a continuación

```
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css
```

## Definición de trabajos

Devuelve una matriz asociativa de trabajos. Cada trabajo puede ser una función de retorno directa (de forma predeterminada `daily`) o una matriz con `schedule` y `callback`:

```php title="cron.php"
return [
    // Expanded format with custom schedule
    'cleanup' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // runs every hour
        },
    ],

    // Shorthand: just a callback, defaults to daily
    'heartbeat' => function () {
        update_option('my_block_last_heartbeat', time());
    },
];
```

### Definiciones nativas de PHP

`cron.php` también puede devolver un objeto con métodos con atributos. Esto ofrece una
interfaz más clara y nativa de PHP, sin dejar de admitir la sintaxis de matriz existente.

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
        update_option('my_block_last_heartbeat', time());
    }

    #[Cron]
    public function cleanupOldEntries(): void {
        // defaults to daily
    }
};
```

De forma predeterminada, los nombres de métodos se normalizan a minúsculas y snake case, así que
`cleanupOldEntries()` se convierte en `cleanup_old_entries`. Usa `name:` si quieres
un nombre de trabajo explícito.

## Programaciones

### Integradas

WordPress incluye estas programaciones de forma predeterminada:

| Programación | Intervalo |
|----------|----------|
| `hourly` | Cada hora |
| `twicedaily` | Cada 12 horas |
| `daily` | Cada 24 horas |
| `weekly` | Cada 7 días |

### Intervalos personalizados

Registra intervalos personalizados mediante el filtro WordPress `cron_schedules` y luego
haz referencia a ellos en `cron.php`:

```php title="functions.php"
add_filter('cron_schedules', function ($schedules) {
    $schedules['every_five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes',
    ];
    $schedules['every_fifteen_minutes'] = [
        'interval' => 900,
        'display'  => 'Every 15 Minutes',
    ];
    return $schedules;
});
```

```php title="cron.php"
return [
    'check_external_api' => [
        'schedule' => 'every_five_minutes',
        'callback' => function () { /* ... */ },
    ],
];
```

## Patrones comunes

### Mantenimiento de datos

Limpia registros antiguos, caduca pruebas, archiva entradas inactivas:

```php title="cron.php"
use Blockstudio\Db;

return [
    'expire_trials' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db     = Db::get('my-theme/app', 'subscribers');
            $trials = $db->list(['plan' => 'trial']);

            foreach ($trials as $trial) {
                if (strtotime($trial['created_at']) < strtotime('-14 days')) {
                    $db->update((int) $trial['id'], ['plan' => 'expired']);
                }
            }
        },
    ],
    'purge_old_logs' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'activity_log');
            $logs = $db->list();

            foreach ($logs as $log) {
                if (strtotime($log['created_at']) < strtotime('-90 days')) {
                    $db->delete((int) $log['id']);
                }
            }
        },
    ],
];
```

### Sincronización de API externa

Obtén datos de servicios de terceros según una programación:

```php title="cron.php"
return [
    'sync_products' => [
        'schedule' => 'hourly',
        'callback' => function () {
            $response = wp_remote_get('https://api.example.com/products');

            if (is_wp_error($response)) {
                return;
            }

            $products = json_decode(wp_remote_retrieve_body($response), true);
            $db       = \Blockstudio\Db::get('my-theme/shop', 'products');

            foreach ($products as $product) {
                $existing = $db->list(['external_id' => $product['id']]);

                if (empty($existing)) {
                    $db->create($product);
                } else {
                    $db->update((int) $existing[0]['id'], $product);
                }
            }
        },
    ],
];
```

### Notificaciones y resúmenes

Envía informes periódicos o correos electrónicos de notificación:

```php title="cron.php"
use Blockstudio\Db;

return [
    'weekly_digest' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'subscribers');
            $new  = count($db->list(['status' => 'active']));
            $admin = get_option('admin_email');

            wp_mail($admin, 'Weekly Digest', "Active subscribers: $new");
        },
    ],
];
```

## Desactivación

Cuando Blockstudio se instala como plugin independiente, al desactivarlo se cancelan automáticamente todos los eventos Blockstudio cron.

Una instalación de Composer dentro de un tema u otro plugin no tiene su propio hook de desactivación. Al desactivar el plugin que lo aloja, cambiar de tema o eliminar el código incluido, los eventos siguen programados, a menos que el host se encargue de limpiarlos. Ejecuta el comando de desinstalación **antes** de hacer cualquiera de estas cosas:

```bash
wp bs teardown
```

Desprograma todos los eventos Blockstudio cron y elimina el estado estático de prerenderizado que pertenece a la instalación. Consulta [CLI](https://blockstudio.dev/es/docs/dev/cli/#teardown) para obtener más detalles.

El comando solo está disponible mientras Blockstudio siga cargado. Como alternativa, un plugin host puede registrar la limpieza en su archivo principal:

```php title="my-plugin.php"
register_deactivation_hook(__FILE__, function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});
```

Un tema que incluya el paquete puede usar la misma devolución de llamada en `switch_theme`. Regístrala mientras el tema anterior siga cargado, no en el hook `after_switch_theme` del tema siguiente:

```php title="functions.php"
add_action('switch_theme', function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});
```

`Cron::unschedule_all()` elimina todos los eventos Blockstudio cron, no solo los trabajos de un bloque o host. Estos hooks no eliminan el estado prerenderizado estático; usa `wp bs teardown` al retirar toda la instalación. Sin limpieza, los eventos periódicos permanecen en WordPress y pueden reanudarse si se vuelve a instalar el código del bloque.

## Filtro

Modificar o desactivar trabajos mediante programación:

```php title="functions.php"
add_filter('blockstudio/cron', function (array $jobs): array {
    // Disable a specific job
    unset($jobs['my-theme/app']['cleanup']);

    // Change a schedule
    if (isset($jobs['my-theme/app']['sync'])) {
        $jobs['my-theme/app']['sync']['schedule'] = 'twicedaily';
    }

    return $jobs;
});
```

## Depuración

WordPress Cron se activa al visitar páginas, no mediante un programador a nivel del sistema.
En sitios con poco tráfico, es posible que los trabajos no se ejecuten exactamente a la hora prevista. Para una programación fiable,
configure un programador del sistema real cron que acceda a `wp-cron.php`:

```bash
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1
```

Luego desactive el activador integrado de WordPress cron en `wp-config.php`:

```php
define('DISABLE_WP_CRON', true);
```

Para consultar los eventos programados, use WP-CLI:

```bash
wp cron event list | grep blockstudio
```
