# Sostituzione di WP-Cron

Queuety può sostituire il sistema integrato WordPress cron. Una volta attivato, le chiamate a `wp_schedule_event()` vengono intercettate e instradate tramite lo scheduler di Queuety invece che tramite il meccanismo WP-Cron predefinito. Gli eventi dovrebbero essere elaborati dal worker Queuety, che consente l’esecuzione indipendentemente dal traffico del sito.

> **Limite attuale:** il bridge crea gli schedule Queuety, ma il worker non dispone di un handler per i job `__queuety_cron_{hook}` che generano, quindi le callback originali di WordPress non vengono mai eseguite. Ogni job fallisce, viene ritentato con backoff e infine messo da parte ([#9](https://github.com/inline0/queuety/issues/9)). Non attivate il bridge su un sito i cui eventi cron devono essere eseguiti finché il problema non viene risolto.

## Attivare la sostituzione

Chiama `Queuety::replace_wp_cron()` all’inizio dell’inizializzazione del plugin o del tema:

```php
use Queuety\Queuety;

Queuety::replace_wp_cron();
```

In genere viene chiamata nel file principale del plugin o in un hook `plugins_loaded`. Deve essere chiamata quando WordPress è caricato (il plugin deve essere attivo).

## Cosa intercetta

Il bridge cron si collega a tre filtri WordPress:

| Funzione WordPress | Filtro collegato | Comportamento |
|---|---|---|
| `wp_schedule_event()` | `pre_schedule_event` | Crea uno schedule Queuety con lo stesso intervallo |
| `wp_unschedule_event()` | `pre_unschedule_event` | Rimuove lo schedule Queuety corrispondente |
| `wp_get_scheduled_event()` | `pre_get_scheduled_event` | Restituisce i dati dello schedule da Queuety |

Vengono intercettati solo gli eventi **ricorrenti** (quelli con una proprietà `schedule` come `hourly`, `twicedaily`, `daily`). Gli eventi singoli pianificati con `wp_schedule_single_event()` non vengono intercettati.

## Come vengono mappati gli eventi

Quando un plugin chiama `wp_schedule_event()`, Queuety risolve il nome dello schedule tramite `wp_get_schedules()`, crea uno schedule Queuety con il nome dell’handler `__queuety_cron_{hook}` e memorizza nel payload dello schedule il nome originale dell’hook WordPress e i relativi argomenti.

L’idea è che il worker Queuety che elabora il job pianificato chiami `do_action()` con il nome originale dell’hook e i relativi argomenti, così le callback esistenti di WordPress vengono eseguite e Queuety ne gestisce la tempistica. `CronBridge::process_cron_event()` implementa questa chiamata, ma al momento non la invoca nulla (vedi il limite descritto sopra). Gli schedule vengono inoltre valutati solo da un processo `wp queuety work` a lunga esecuzione, circa una volta al minuto (vedi [Pianificazione](https://queuety.inline0.dev/it/docs/features/scheduling)).

### Risoluzione degli intervalli

Il bridge risolve prima i nomi degli schedule tramite `wp_get_schedules()`, poi ricorre ai valori predefiniti integrati:

| Nome dello schedule | Intervallo |
|---|---|
| `hourly` | 3,600 secondi |
| `twicedaily` | 43,200 secondi |
| `daily` | 86,400 secondi |
| `weekly` | 604,800 secondi |

Sono supportati gli intervalli di schedule personalizzati registrati tramite il filtro `cron_schedules`, purché `wp_get_schedules()` li restituisca.

## Ripristinare WP-Cron

Per tornare al sistema WordPress cron predefinito:

```php
Queuety::restore_wp_cron();
```

In questo modo vengono rimossi gli hook dei filtri e WordPress può gestire nuovamente gli eventi cron tramite il proprio meccanismo integrato. Nota: quando viene installato il bridge, `DISABLE_WP_CRON` viene definita come `true` e non può essere annullata durante l’esecuzione; potrebbe quindi essere necessario rimuovere la costante da `wp-config.php` o riavviare il processo.

## Quando usarlo

La sostituzione è particolarmente utile quando il sito ha poco traffico, quando serve una tempistica più affidabile di quella offerta da WP-Cron o quando sono già in esecuzione worker Queuety e si vuole gestire l’esecuzione di cron nello stesso sistema operativo. È utile anche quando serve un’osservabilità centralizzata, perché gli eventi cron compaiono quindi negli stessi log e nelle stesse metriche degli altri job in coda.

## Limitazioni

Ci sono alcuni vincoli importanti. È necessario che sia attivo un worker Queuety, altrimenti gli eventi pianificati non verranno mai eseguiti. Vengono intercettati solo gli schedule ricorrenti; gli eventi singoli creati con `wp_schedule_single_event()` restano fuori dal bridge. Inoltre, `replace_wp_cron()` definisce `DISABLE_WP_CRON` per il resto del processo PHP corrente, quindi `restore_wp_cron()` rimuove gli hook ma non può annullare la definizione della costante. Infine, il bridge funziona solo quando WordPress è caricato, perché dipende dai filtri WordPress e da `do_action()`.

## Esempio: configurazione completa

```php
use Queuety\Queuety;

// In your plugin's main file.
add_action( 'plugins_loaded', function () {
    Queuety::replace_wp_cron();
} );
```

Qui non è necessario chiamare `Queuety::init()`: il plugin Queuety attivo crea la connessione usando le credenziali del database WordPress e si inizializza su `plugins_loaded`. `replace_wp_cron()` installa solo i filtri, quindi non dipende dal fatto che questa operazione sia già avvenuta.

A questo punto, gli eventi ricorrenti che i plugin registrano con `wp_schedule_event()` vengono memorizzati come schedule Queuety. Finché il problema di [#9](https://github.com/inline0/queuety/issues/9) non viene risolto, le relative callback non vengono eseguite.