|
| 1 | +# Filters Reference |
| 2 | + |
| 3 | +This document lists all public WordPress filters exposed by the Redis Queue plugin (excluding third‑party library filters). Use these hooks to customize behaviour without modifying core plugin code. |
| 4 | + |
| 5 | +> Prefix: All filters start with `redis_queue_`. |
| 6 | +
|
| 7 | +## Table of Contents |
| 8 | +- [UI / Admin](#ui--admin) |
| 9 | +- [Job Creation & Mapping](#job-creation--mapping) |
| 10 | +- [Job Retry & Backoff](#job-retry--backoff) |
| 11 | +- [Job Payload Validation](#job-payload-validation) |
| 12 | +- [REST API Token Scopes](#rest-api-token-scopes) |
| 13 | + |
| 14 | +--- |
| 15 | +## UI / Admin |
| 16 | +### `redis_queue_show_test_jobs_page` |
| 17 | +Controls whether the "Test Jobs" submenu appears in the admin and whether the page can be accessed directly. |
| 18 | + |
| 19 | +| Type | Default | Since | |
| 20 | +|------|---------|-------| |
| 21 | +| bool | `true` | 2.0.1 | |
| 22 | + |
| 23 | +Return `false` to hide the menu and block direct access (useful for production hardening). |
| 24 | + |
| 25 | +```php |
| 26 | +// In mu-plugin or theme functions.php |
| 27 | +add_filter( 'redis_queue_show_test_jobs_page', '__return_false' ); |
| 28 | +``` |
| 29 | + |
| 30 | +--- |
| 31 | +## Job Creation & Mapping |
| 32 | +### `redis_queue_create_job` |
| 33 | +Allows creation of custom job instances for dynamic job types that are not part of the built‑in set (`email`, `image_processing`, `api_sync`). |
| 34 | + |
| 35 | +Signature: |
| 36 | +```php |
| 37 | +apply_filters( 'redis_queue_create_job', $job_or_null, string $job_type, array $payload ); |
| 38 | +``` |
| 39 | +- `$job_or_null` (mixed): Always `null` on input; return a `Queue_Job` instance to handle the type. |
| 40 | +- `$job_type` (string): Requested job type. |
| 41 | +- `$payload` (array): Raw payload passed by caller. |
| 42 | + |
| 43 | +Return: `\Soderlind\RedisQueue\Contracts\Queue_Job|null`. |
| 44 | + |
| 45 | +Example: |
| 46 | +```php |
| 47 | +add_filter( 'redis_queue_create_job', function( $job, $type, $payload ) { |
| 48 | + if ( 'report_generation' !== $type ) { |
| 49 | + return $job; // leave untouched |
| 50 | + } |
| 51 | + return new \MyPlugin\Jobs\Report_Generation_Job( $payload ); |
| 52 | +}, 10, 3 ); |
| 53 | +``` |
| 54 | + |
| 55 | +### `redis_queue_job_classes` |
| 56 | +Extends or overrides the canonical mapping from simple job type identifiers (lowercase) to fully qualified job class names used during deserialization / processing by the `Job_Processor`. |
| 57 | + |
| 58 | +Signature: |
| 59 | +```php |
| 60 | +apply_filters( 'redis_queue_job_classes', array $map ); |
| 61 | +``` |
| 62 | +- `$map` (array): Base mapping like `['email' => Email_Job::class, ...]`. |
| 63 | + |
| 64 | +Return: Modified associative array. |
| 65 | + |
| 66 | +Example (add `report_generation`): |
| 67 | +```php |
| 68 | +add_filter( 'redis_queue_job_classes', function( $map ) { |
| 69 | + $map['report_generation'] = \MyPlugin\Jobs\Report_Generation_Job::class; |
| 70 | + return $map; |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +--- |
| 75 | +## Job Retry & Backoff |
| 76 | +### `redis_queue_should_retry_job` |
| 77 | +Determines if a failed job should be retried (only consulted if current attempts < max_attempts). |
| 78 | + |
| 79 | +Signature: |
| 80 | +```php |
| 81 | +apply_filters( 'redis_queue_should_retry_job', bool $should_retry, Queue_Job $job, ?\Exception $exception, int $attempt ); |
| 82 | +``` |
| 83 | +- `$should_retry` (bool): Default `true` after basic guards. |
| 84 | +- `$job` (Queue_Job): Job instance. |
| 85 | +- `$exception` (?Exception): The exception that caused failure or `null` when failure was non-exception based. |
| 86 | +- `$attempt` (int): Current attempt number (1-based) that just failed. |
| 87 | + |
| 88 | +Return: `bool` (retry or not). |
| 89 | + |
| 90 | +Example (disable retries on specific exception): |
| 91 | +```php |
| 92 | +add_filter( 'redis_queue_should_retry_job', function( $retry, $job, $exception, $attempt ) { |
| 93 | + if ( $exception instanceof \MyPlugin\FatalRemoteAPIException ) { |
| 94 | + return false; // don't bother retrying |
| 95 | + } |
| 96 | + return $retry; |
| 97 | +}, 10, 4 ); |
| 98 | +``` |
| 99 | + |
| 100 | +### `redis_queue_job_retry_delay` |
| 101 | +Adjusts delay (seconds) before a retry attempt is re-enqueued. |
| 102 | + |
| 103 | +Signature: |
| 104 | +```php |
| 105 | +apply_filters( 'redis_queue_job_retry_delay', int $delay, Queue_Job $job, int $attempt ); |
| 106 | +``` |
| 107 | +- `$delay` (int): Computed delay (configured backoff item or exponential fallback capped at 3600s). |
| 108 | +- `$job` (Queue_Job): Job instance. |
| 109 | +- `$attempt` (int): Attempt number that just failed. |
| 110 | + |
| 111 | +Return: New delay (int). |
| 112 | + |
| 113 | +Example (progressive jitter): |
| 114 | +```php |
| 115 | +add_filter( 'redis_queue_job_retry_delay', function( $delay, $job, $attempt ) { |
| 116 | + return (int) ( $delay * ( 0.9 + mt_rand() / mt_getrandmax() * 0.2 ) ); |
| 117 | +}, 10, 3 ); |
| 118 | +``` |
| 119 | + |
| 120 | +--- |
| 121 | +## Job Payload Validation |
| 122 | +### `redis_queue_validate_job_payload` |
| 123 | +Override or augment validation of a job payload. |
| 124 | + |
| 125 | +Signature: |
| 126 | +```php |
| 127 | +apply_filters( 'redis_queue_validate_job_payload', bool $is_valid, array $payload, Queue_Job $job ); |
| 128 | +``` |
| 129 | +- `$is_valid` (bool): Default `true`. |
| 130 | +- `$payload` (array): Job payload. |
| 131 | +- `$job` (Queue_Job): Job instance. |
| 132 | + |
| 133 | +Return: `bool` (allow enqueue / continue processing). |
| 134 | + |
| 135 | +Example (require key): |
| 136 | +```php |
| 137 | +add_filter( 'redis_queue_validate_job_payload', function( $valid, $payload, $job ) { |
| 138 | + if ( 'report_generation' === $job->get_job_type() && empty( $payload['report_id'] ) ) { |
| 139 | + return false; |
| 140 | + } |
| 141 | + return $valid; |
| 142 | +}, 10, 3 ); |
| 143 | +``` |
| 144 | + |
| 145 | +--- |
| 146 | +## REST API Token Scopes |
| 147 | +These filters control what endpoints a token with a restricted scope may access. |
| 148 | + |
| 149 | +### `redis_queue_token_allowed_routes` |
| 150 | +Defines the list of allowable REST routes for a non-`full` scope token before per-request evaluation. |
| 151 | + |
| 152 | +Signature: |
| 153 | +```php |
| 154 | +apply_filters( 'redis_queue_token_allowed_routes', array $routes, string $scope ); |
| 155 | +``` |
| 156 | +- `$routes` (array): Default `[ '/redis-queue/v1/workers/trigger' ]` when scope != `full`. |
| 157 | +- `$scope` (string): Token scope, e.g. `worker` or `full`. |
| 158 | + |
| 159 | +Return: Adjusted list of route paths. |
| 160 | + |
| 161 | +Example (allow stats endpoint): |
| 162 | +```php |
| 163 | +add_filter( 'redis_queue_token_allowed_routes', function( $routes, $scope ) { |
| 164 | + if ( 'worker' === $scope ) { |
| 165 | + $routes[] = '/redis-queue/v1/stats'; |
| 166 | + } |
| 167 | + return $routes; |
| 168 | +}, 10, 2 ); |
| 169 | +``` |
| 170 | + |
| 171 | +### `redis_queue_token_scope_allow` |
| 172 | +Final gate to allow/deny a request for a token (after URL match). Use to implement dynamic rules (time windows, IP allowlists, etc.). |
| 173 | + |
| 174 | +Signature: |
| 175 | +```php |
| 176 | +apply_filters( 'redis_queue_token_scope_allow', bool $allowed, string $scope, WP_REST_Request $request ); |
| 177 | +``` |
| 178 | +- `$allowed` (bool): Result after earlier checks. |
| 179 | +- `$scope` (string): Token scope. |
| 180 | +- `$request` (WP_REST_Request): Full request object. |
| 181 | + |
| 182 | +Return: `bool` (permit request?). |
| 183 | + |
| 184 | +Example (block trigger outside office hours): |
| 185 | +```php |
| 186 | +add_filter( 'redis_queue_token_scope_allow', function( $allowed, $scope, $request ) { |
| 187 | + if ( 'worker' === $scope ) { |
| 188 | + $hour = (int) gmdate('G'); |
| 189 | + if ( $hour < 6 || $hour > 22 ) { |
| 190 | + return false; // Outside allowed window |
| 191 | + } |
| 192 | + } |
| 193 | + return $allowed; |
| 194 | +}, 10, 3 ); |
| 195 | +``` |
| 196 | + |
| 197 | +--- |
| 198 | +## Notes |
| 199 | +- All filters follow standard WordPress priority & argument count conventions. |
| 200 | +- Always return the original value when not modifying behaviour to maintain chain integrity. |
| 201 | +- Avoid expensive operations inside hot-path filters (`job_retry_delay`, `should_retry_job`). |
| 202 | + |
| 203 | +Happy extending! 🚀 |
0 commit comments