# WP-Cron Replacement

Queuety can replace the built-in WordPress cron system. When enabled, calls to `wp_schedule_event()` are intercepted and routed through Queuety's scheduler instead of the default WP-Cron mechanism. Events are processed by the Queuety worker, which provides reliable execution independent of site traffic.

## Enabling the replacement

Call `Queuety::replace_wp_cron()` early in your plugin or theme initialization:

```php
use Queuety\Queuety;

Queuety::replace_wp_cron();
```

This is typically called in your plugin's main file or in a `plugins_loaded` hook. It must be called while WordPress is loaded (the plugin must be active).

## What it intercepts

The cron bridge hooks into three WordPress filters:

| WordPress function | Filter hooked | Behavior |
|---|---|---|
| `wp_schedule_event()` | `pre_schedule_event` | Creates a Queuety schedule with the same interval |
| `wp_unschedule_event()` | `pre_unschedule_event` | Removes the corresponding Queuety schedule |
| `wp_get_scheduled_event()` | `pre_get_scheduled_event` | Returns schedule data from Queuety |

Only **recurring** events (those with a `schedule` property like `hourly`, `twicedaily`, `daily`) are intercepted. Single-fire events scheduled with `wp_schedule_single_event()` are not intercepted.

## How events are mapped

When a plugin calls `wp_schedule_event()`, Queuety resolves the schedule name through `wp_get_schedules()`, creates a Queuety schedule with the handler name `__queuety_cron_{hook}`, and stores the original WordPress hook name and arguments in the schedule payload.

Later, when the Queuety worker processes that scheduled job, it calls `do_action()` with the original hook name and arguments. The existing WordPress callbacks still run as normal; the difference is only that the timing and dispatch are now driven by Queuety instead of traffic-triggered WP-Cron.

### Interval resolution

The bridge resolves schedule names through `wp_get_schedules()` first, then falls back to built-in defaults:

| Schedule name | Interval |
|---|---|
| `hourly` | 3,600 seconds |
| `twicedaily` | 43,200 seconds |
| `daily` | 86,400 seconds |
| `weekly` | 604,800 seconds |

Custom schedule intervals registered via the `cron_schedules` filter are supported as long as `wp_get_schedules()` returns them.

## Restoring WP-Cron

To revert to the default WordPress cron system:

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

This removes the filter hooks and allows WordPress to handle cron events through its built-in mechanism again. Note that `DISABLE_WP_CRON` is defined as `true` when the bridge is installed and cannot be un-defined at runtime, so you may need to remove that constant from `wp-config.php` or restart the process.

## When to use it

The replacement is most useful when your site has low traffic, when you need more reliable timing than WP-Cron can provide, or when you are already running Queuety workers and want cron execution to live in the same operational system. It also helps when centralized observability matters, because cron events then show up in the same logs and metrics as your other queue work.

## Limitations

There are a few important constraints. An active Queuety worker is required, otherwise the scheduled events will never run. Only recurring schedules are intercepted; single-fire events created with `wp_schedule_single_event()` still stay outside the bridge. `replace_wp_cron()` also defines `DISABLE_WP_CRON` for the rest of the current PHP process, so `restore_wp_cron()` removes the hooks but cannot un-define the constant. Finally, the bridge only works when WordPress is loaded, because it depends on WordPress filters and `do_action()`.

## Example: full setup

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

After this, any plugin that calls `wp_schedule_event()` will have its events routed through Queuety automatically. The original hook callbacks continue to work without modification.