# Substituição de WP-Cron

Queuety pode substituir o sistema integrado de WordPress cron. Quando ativado, as chamadas a `wp_schedule_event()` são interceptadas e encaminhadas pelo agendador do Queuety em vez de usar o mecanismo padrão WP-Cron. Os eventos devem ser processados pelo worker Queuety, que executa de forma independente do tráfego do site.

> **Limitação atual:** a ponte cria os agendamentos Queuety, mas o worker não tem um handler para as tarefas `__queuety_cron_{hook}` que eles produzem; portanto, os callbacks originais WordPress nunca são executados. Cada tarefa falha, é processada novamente após um intervalo e acaba sendo colocada em espera ([#9](https://github.com/inline0/queuety/issues/9)). Não ative a ponte em um site cujos eventos cron precisem ser executados até que isso seja corrigido.

## Ativando a substituição

Chame `Queuety::replace_wp_cron()` no início da inicialização do seu plugin ou tema:

```php
use Queuety\Queuety;

Queuety::replace_wp_cron();
```

Isso normalmente é chamado no arquivo principal do seu plugin ou em um hook `plugins_loaded`. Deve ser chamado enquanto WordPress estiver carregado (o plugin deve estar ativo).

## O que ele intercepta

A ponte cron se conecta a três filtros WordPress:

| Função WordPress | Filtro conectado | Comportamento |
|---|---|---|
| `wp_schedule_event()` | `pre_schedule_event` | Cria um agendamento Queuety com o mesmo intervalo |
| `wp_unschedule_event()` | `pre_unschedule_event` | Remove o agendamento Queuety correspondente |
| `wp_get_scheduled_event()` | `pre_get_scheduled_event` | Retorna dados de agendamento de Queuety |

Somente eventos **recorrentes** (aqueles com uma propriedade `schedule` como `hourly`, `twicedaily`, `daily`) são interceptados. Eventos únicos agendados com `wp_schedule_single_event()` não são interceptados.

## Como os eventos são mapeados

Quando um plugin chama `wp_schedule_event()`, Queuety resolve o nome do agendamento por meio de `wp_get_schedules()`, cria um agendamento Queuety com o nome do manipulador `__queuety_cron_{hook}` e armazena o nome do hook WordPress original e os argumentos na carga útil do agendamento.

O comportamento pretendido é que o worker Queuety que processa o job agendado chame `do_action()` com o nome do hook original e os argumentos, para que os callbacks WordPress existentes sejam executados com Queuety controlando o tempo. `CronBridge::process_cron_event()` implementa essa chamada, mas nada a invoca ainda (consulte a limitação acima). Os agendamentos também são avaliados apenas por um processo `wp queuety work` de longa duração, aproximadamente uma vez por minuto (consulte [Agendamento](https://queuety.inline0.dev/pt/docs/features/scheduling)).

### Resolução do intervalo

A ponte resolve primeiro os nomes dos agendamentos por meio de `wp_get_schedules()` e, em seguida, recorre aos padrões integrados:

| Nome do agendamento | Intervalo |
|---|---|
| `hourly` | 3,600 segundos |
| `twicedaily` | 43,200 segundos |
| `daily` | 86,400 segundos |
| `weekly` | 604,800 segundos |

Há suporte para intervalos de agendamento personalizados registrados pelo filtro `cron_schedules`, desde que `wp_get_schedules()` os retorne.

## Restaurando WP-Cron

Para voltar ao sistema WordPress cron padrão:

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

Isso remove os hooks de filtro e permite que WordPress volte a lidar com eventos cron pelo mecanismo integrado. Observe que `DISABLE_WP_CRON` é definido como `true` quando a ponte é instalada e não pode ser desdefinido em tempo de execução; por isso, talvez seja necessário remover essa constante de `wp-config.php` ou reiniciar o processo.

## Quando usar

A substituição é mais útil quando seu site tem pouco tráfego, quando você precisa de um agendamento mais confiável do que WP-Cron pode oferecer ou quando já executa workers Queuety e quer que a execução cron faça parte do mesmo sistema operacional. Ela também ajuda quando a observabilidade centralizada é importante, pois os eventos cron aparecem nos mesmos logs e métricas dos demais jobs da fila.

## Limitações

Há algumas limitações importantes. É necessário ter um worker Queuety ativo; caso contrário, os eventos agendados nunca serão executados. Somente agendamentos recorrentes são interceptados; eventos únicos criados com `wp_schedule_single_event()` continuam fora da ponte. `replace_wp_cron()` também define `DISABLE_WP_CRON` para o restante do processo PHP atual, então `restore_wp_cron()` remove os hooks, mas não pode desdefinir a constante. Por fim, a ponte só funciona quando WordPress está carregado, pois depende dos filtros WordPress e de `do_action()`.

## Exemplo: configuração completa

```php
use Queuety\Queuety;

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

Não é necessário chamar `Queuety::init()` aqui: o plugin Queuety ativo cria sua conexão usando as credenciais do banco de dados WordPress e se inicializa em `plugins_loaded`. `replace_wp_cron()` apenas instala os filtros, portanto não depende de que isso tenha ocorrido antes.

Depois disso, os eventos recorrentes registrados pelos plugins com `wp_schedule_event()` são armazenados como agendamentos Queuety. Até que [#9](https://github.com/inline0/queuety/issues/9) seja corrigido, os callbacks não serão executados.