# 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 ブリッジは、次の3つの 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()` を呼び出し、既存の WordPress コールバックを Queuety によるタイミング管理のもとで実行します。`CronBridge::process_cron_event()` はその呼び出しを実装していますが、まだ呼び出すものがありません（上記の制限事項を参照）。また、スケジュールの評価は長時間稼働する `wp queuety work` プロセスによってのみ、約1分ごとに行われます（[スケジューリング](https://queuety.inline0.dev/ja/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) が修正されるまでは、これらのコールバックは実行されません。