# WP-Cron 대체

Queuety은 내장 WordPress cron 시스템을 대체할 수 있습니다. 활성화하면 `wp_schedule_event()` 호출을 가로채 기본 WP-Cron 방식 대신 Queuety의 스케줄러를 통해 라우팅합니다. 이벤트는 사이트 트래픽과 독립적으로 실행되는 Queuety 워커가 처리하도록 설계되었습니다.

> **현재 제한 사항:** 브리지는 Queuety 일정을 생성하지만, 워커에는 이 일정이 생성하는 `__queuety_cron_{hook}` 작업을 처리할 핸들러가 없어 원래 WordPress 콜백이 실행되지 않습니다. 각 작업은 실패한 뒤 지연 시간을 두고 재시도되며, 결국 묻힙니다([#9](https://github.com/inline0/queuety/issues/9)). 이 문제가 해결될 때까지 cron 이벤트를 실행해야 하는 사이트에서는 브리지를 활성화하지 마세요.

## 대체 기능 활성화

플러그인이나 테마 초기화 초기에 `Queuety::replace_wp_cron()`을 호출하세요.

```php
use Queuety\Queuety;

Queuety::replace_wp_cron();
```

일반적으로 플러그인의 기본 파일이나 `plugins_loaded` 훅에서 호출합니다. WordPress이 로드된 상태에서 호출해야 합니다(플러그인이 활성화되어 있어야 함).

## 가로채는 항목

cron 브리지는 세 가지 WordPress 필터에 연결됩니다.

| WordPress 함수 | 연결된 필터 | 동작 |
|---|---|---|
| `wp_schedule_event()` | `pre_schedule_event` | 같은 간격으로 Queuety 일정을 생성합니다 |
| `wp_unschedule_event()` | `pre_unschedule_event` | 해당 Queuety 일정을 제거합니다 |
| `wp_get_scheduled_event()` | `pre_get_scheduled_event` | Queuety에서 일정 데이터를 반환합니다 |

`schedule` 속성이 있는 이벤트(예: `hourly`, `twicedaily`, `daily`)처럼 **반복되는** 이벤트만 가로챕니다. `wp_schedule_single_event()`로 예약한 단발성 이벤트는 가로채지 않습니다.

## 이벤트 매핑 방식

플러그인이 `wp_schedule_event()`을 호출하면 Queuety은 `wp_get_schedules()`를 통해 일정 이름을 확인하고, 핸들러 이름이 `__queuety_cron_{hook}`인 Queuety 일정을 생성한 뒤 원래 WordPress 훅 이름과 인수를 일정 페이로드에 저장합니다.

의도된 동작은 Queuety 워커가 예약된 작업을 처리할 때 원래 훅 이름과 인수를 사용해 `do_action()`을 호출하고, Queuety이 실행 시점을 관리하면서 기존 WordPress 콜백을 실행하는 것입니다. `CronBridge::process_cron_event()`에는 해당 호출이 구현되어 있지만 아직 호출하는 곳은 없습니다(위 제한 사항 참조). 일정은 장기 실행 `wp queuety work` 프로세스에서만 평가되며, 약 1분에 한 번 실행됩니다([스케줄링](https://queuety.inline0.dev/ko/docs/features/scheduling) 참조).

### 간격 확인

브리지는 먼저 `wp_get_schedules()`을 통해 일정 이름을 확인한 다음 기본 제공 기본값을 사용합니다.

| 일정 이름 | 간격 |
|---|---|
| `hourly` | 3,600초 |
| `twicedaily` | 43,200초 |
| `daily` | 86,400초 |
| `weekly` | 604,800초 |

`cron_schedules` 필터로 등록한 사용자 지정 일정 간격은 `wp_get_schedules()`이 해당 값을 반환하는 한 지원됩니다.

## WP-Cron 복원

기본 WordPress cron 시스템으로 되돌리려면 다음을 실행하세요.

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

이렇게 하면 필터 훅이 제거되고 WordPress이 내장 방식으로 cron 이벤트를 다시 처리합니다. 브리지를 설치할 때 `DISABLE_WP_CRON`은 `true`으로 정의되며 런타임에 정의를 해제할 수 없으므로, `wp-config.php`에서 해당 상수를 제거하거나 프로세스를 다시 시작해야 할 수 있습니다.

## 사용 시점

사이트 트래픽이 적거나 WP-Cron보다 더 안정적인 실행 시점이 필요하거나, 이미 Queuety 워커를 실행하고 cron 실행도 같은 운영 시스템에서 처리하려는 경우 이 대체 기능이 유용합니다. 중앙 집중식 관측 가능성이 중요할 때도 도움이 됩니다. cron 이벤트가 다른 대기열 작업과 같은 로그 및 메트릭에 표시되기 때문입니다.

## 제한 사항

몇 가지 중요한 제약이 있습니다. 예약된 이벤트를 실행하려면 Queuety 워커가 실행 중이어야 합니다. 반복 일정만 가로채며 `wp_schedule_single_event()`으로 생성한 단발성 이벤트는 브리지 밖에 그대로 남습니다. `replace_wp_cron()`도 현재 PHP 프로세스가 실행되는 동안 `DISABLE_WP_CRON`을 정의하므로, `restore_wp_cron()`은 훅을 제거하지만 상수 정의를 해제할 수 없습니다. 마지막으로 브리지는 WordPress이 로드된 경우에만 작동합니다. WordPress 필터와 `do_action()`에 의존하기 때문입니다.

## 예시: 전체 설정

```php
use Queuety\Queuety;

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

여기서는 `Queuety::init()`을 호출할 필요가 없습니다. 활성화된 Queuety 플러그인이 WordPress 데이터베이스 인증 정보를 사용해 연결을 만들고 `plugins_loaded`에서 자체적으로 초기화됩니다. `replace_wp_cron()`는 필터만 설치하므로 해당 초기화가 먼저 이루어질 필요가 없습니다.

이후 플러그인이 `wp_schedule_event()`으로 등록하는 반복 이벤트는 Queuety 일정으로 저장됩니다. [#9](https://github.com/inline0/queuety/issues/9) 문제가 해결될 때까지 콜백은 실행되지 않습니다.