Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit ecb790c

Browse files
feat: Queue::push() to return QueuePushResult instead of boolean (#62)
* feat: return jobID after push instead of the bool value * fix phpcpd * feat: return QueuePushResult from push() instead of bool * add some PHPDocs to QueuePushResult class
1 parent 39f0a8b commit ecb790c

13 files changed

+217
-41
lines changed

‎docs/basic-usage.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,12 @@ service('queue')->push('emails', 'email', ['message' => 'Email message goes here
160160

161161
We will be pushing `email` job to the `emails` queue.
162162

163+
As a result of calling the `push()` method, you will receive a `QueuePushResult` object, which you can inspect if needed. It provides the following information:
164+
165+
- `getStatus()`: Indicates whether the job was successfully added to the queue.
166+
- `getJobId()`: Returns the ID of the job that was added to the queue.
167+
- `getError()`: Returns any error that occurred if the job was not added.
168+
163169
### Sending chained jobs to the queue
164170

165171
Sending chained jobs is also simple and lets you specify the particular order of the job execution.
@@ -172,9 +178,11 @@ service('queue')->chain(function($chain) {
172178
});
173179
```
174180

175-
In the example above, we will send jobs to the `reports` and `emails` queue. First, we will generate a report for given user with the `generate-report` job, after this, we will send an email with `email` job.
181+
In the example above, we will send jobs to the `reports` and `emails` queues. First, we will generate a report for given user with the `generate-report` job, after this, we will send an email with `email` job.
176182
The `email` job will be executed only if the `generate-report` job was successful.
177183

184+
As with the `push()` method, calling the `chain()` method also returns a `QueuePushResult` object.
185+
178186
### Consuming the queue
179187

180188
Since we sent our sample job to queue `emails`, then we need to run the worker with the appropriate queue:

‎src/Handlers/BaseHandler.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use CodeIgniter\Queue\Models\QueueJobFailedModel;
2323
use CodeIgniter\Queue\Payloads\ChainBuilder;
2424
use CodeIgniter\Queue\Payloads\PayloadMetadata;
25+
use CodeIgniter\Queue\QueuePushResult;
2526
use CodeIgniter\Queue\Traits\HasQueueValidation;
2627
use ReflectionException;
2728
use Throwable;
@@ -39,7 +40,7 @@ abstract class BaseHandler
3940

4041
abstract public function name(): string;
4142

42-
abstract public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): bool;
43+
abstract public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): QueuePushResult;
4344

4445
abstract public function pop(string $queue, array $priorities): ?QueueJob;
4546

@@ -153,7 +154,7 @@ public function setPriority(string $priority): static
153154
*
154155
* @param Closure $callback Chain definition callback
155156
*/
156-
public function chain(Closure $callback): bool
157+
public function chain(Closure $callback): QueuePushResult
157158
{
158159
$chainBuilder = new ChainBuilder($this);
159160
$callback($chainBuilder);

‎src/Handlers/DatabaseHandler.php‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
use CodeIgniter\Queue\Models\QueueJobModel;
2222
use CodeIgniter\Queue\Payloads\Payload;
2323
use CodeIgniter\Queue\Payloads\PayloadMetadata;
24+
use CodeIgniter\Queue\QueuePushResult;
2425
use ReflectionException;
2526
use Throwable;
2627

@@ -44,10 +45,8 @@ public function name(): string
4445

4546
/**
4647
* Add job to the queue.
47-
*
48-
* @throws ReflectionException
4948
*/
50-
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): bool
49+
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): QueuePushResult
5150
{
5251
$this->validateJobAndPriority($queue, $job);
5352

@@ -62,7 +61,17 @@ public function push(string $queue, string $job, array $data, ?PayloadMetadata $
6261

6362
$this->priority = $this->delay = null;
6463

65-
return $this->jobModel->insert($queueJob, false);
64+
try {
65+
$jobId = $this->jobModel->insert($queueJob);
66+
} catch (Throwable $e) {
67+
return QueuePushResult::failure($e->getMessage());
68+
}
69+
70+
if ($jobId === 0) {
71+
return QueuePushResult::failure('Failed to insert job into the database.');
72+
}
73+
74+
return QueuePushResult::success($jobId);
6675
}
6776

6877
/**

‎src/Handlers/PredisHandler.php‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use CodeIgniter\Queue\Interfaces\QueueInterface;
2323
use CodeIgniter\Queue\Payloads\Payload;
2424
use CodeIgniter\Queue\Payloads\PayloadMetadata;
25+
use CodeIgniter\Queue\QueuePushResult;
2526
use Exception;
2627
use Predis\Client;
2728
use Throwable;
@@ -59,16 +60,17 @@ public function name(): string
5960
/**
6061
* Add job to the queue.
6162
*/
62-
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): bool
63+
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): QueuePushResult
6364
{
6465
$this->validateJobAndPriority($queue, $job);
6566

6667
helper('text');
6768

69+
$jobId = (int) random_string('numeric', 16);
6870
$availableAt = Time::now()->addSeconds($this->delay ?? 0);
6971

7072
$queueJob = new QueueJob([
71-
'id' => random_string('numeric', 16),
73+
'id' => $jobId,
7274
'queue' => $queue,
7375
'payload' => new Payload($job, $data, $metadata),
7476
'priority' => $this->priority,
@@ -77,11 +79,19 @@ public function push(string $queue, string $job, array $data, ?PayloadMetadata $
7779
'available_at' => $availableAt,
7880
]);
7981

80-
$result = $this->predis->zadd("queues:{$queue}:{$this->priority}", [json_encode($queueJob) => $availableAt->timestamp]);
82+
try {
83+
$result = $this->predis->zadd("queues:{$queue}:{$this->priority}", [json_encode($queueJob) => $availableAt->timestamp]);
84+
} catch (Throwable $e) {
85+
return QueuePushResult::failure('Unexpected Redis error: ' . $e->getMessage());
86+
} finally {
87+
$this->priority = $this->delay = null;
88+
}
8189

8290
$this->priority = $this->delay = null;
8391

84-
return $result > 0;
92+
return $result > 0
93+
? QueuePushResult::success($jobId)
94+
: QueuePushResult::failure('Job already exists in the queue.');
8595
}
8696

8797
/**

‎src/Handlers/RedisHandler.php‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use CodeIgniter\Queue\Interfaces\QueueInterface;
2323
use CodeIgniter\Queue\Payloads\Payload;
2424
use CodeIgniter\Queue\Payloads\PayloadMetadata;
25+
use CodeIgniter\Queue\QueuePushResult;
2526
use Redis;
2627
use RedisException;
2728
use Throwable;
@@ -76,16 +77,17 @@ public function name(): string
7677
*
7778
* @throws RedisException
7879
*/
79-
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): bool
80+
public function push(string $queue, string $job, array $data, ?PayloadMetadata $metadata = null): QueuePushResult
8081
{
8182
$this->validateJobAndPriority($queue, $job);
8283

8384
helper('text');
8485

8586
$availableAt = Time::now()->addSeconds($this->delay ?? 0);
87+
$jobId = (int) random_string('numeric', 16);
8688

8789
$queueJob = new QueueJob([
88-
'id' => random_string('numeric', 16),
90+
'id' => $jobId,
8991
'queue' => $queue,
9092
'payload' => new Payload($job, $data, $metadata),
9193
'priority' => $this->priority,
@@ -94,11 +96,21 @@ public function push(string $queue, string $job, array $data, ?PayloadMetadata $
9496
'available_at' => $availableAt,
9597
]);
9698

97-
$result = (int) $this->redis->zAdd("queues:{$queue}:{$this->priority}", $availableAt->timestamp, json_encode($queueJob));
99+
try {
100+
$result = $this->redis->zAdd("queues:{$queue}:{$this->priority}", $availableAt->timestamp, json_encode($queueJob));
101+
} catch (Throwable $e) {
102+
return QueuePushResult::failure('Unexpected Redis error: ' . $e->getMessage());
103+
} finally {
104+
$this->priority = $this->delay = null;
105+
}
98106

99-
$this->priority = $this->delay = null;
107+
if ($result === false) {
108+
return QueuePushResult::failure('Failed to add job to Redis.');
109+
}
100110

101-
return $result > 0;
111+
return (int) $result > 0
112+
? QueuePushResult::success($jobId)
113+
: QueuePushResult::failure('Job already exists in the queue.');
102114
}
103115

104116
/**

‎src/Payloads/ChainBuilder.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
namespace CodeIgniter\Queue\Payloads;
1515

1616
use CodeIgniter\Queue\Handlers\BaseHandler;
17+
use CodeIgniter\Queue\QueuePushResult;
1718

1819
class ChainBuilder
1920
{
@@ -44,10 +45,10 @@ public function push(string $queue, string $jobName, array $data = []): ChainEle
4445
/**
4546
* Dispatch the chain of jobs
4647
*/
47-
public function dispatch(): bool
48+
public function dispatch(): QueuePushResult
4849
{
4950
if ($this->payloads->count() === 0) {
50-
return true;
51+
return QueuePushResult::failure('No jobs to dispatch.');
5152
}
5253

5354
$current = $this->payloads->shift();

‎src/QueuePushResult.php‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of CodeIgniter Queue.
7+
*
8+
* (c) CodeIgniter Foundation <admin@codeigniter.com>
9+
*
10+
* For the full copyright and license information, please view
11+
* the LICENSE file that was distributed with this source code.
12+
*/
13+
14+
namespace CodeIgniter\Queue;
15+
16+
/**
17+
* Represents the result of a queue push operation.
18+
*/
19+
class QueuePushResult
20+
{
21+
public function __construct(
22+
protected readonly bool $success,
23+
protected readonly ?int $jobId = null,
24+
protected readonly ?string $error = null,
25+
) {
26+
}
27+
28+
/**
29+
* Creates a successful push result.
30+
*/
31+
public static function success(int $jobId): self
32+
{
33+
return new self(true, $jobId);
34+
}
35+
36+
/**
37+
* Creates a failed push result.
38+
*/
39+
public static function failure(?string $error = null): self
40+
{
41+
return new self(false, null, $error);
42+
}
43+
44+
/**
45+
* Returns whether the push operation was successful.
46+
*/
47+
public function getStatus(): bool
48+
{
49+
return $this->success;
50+
}
51+
52+
/**
53+
* Returns the job ID if the push was successful, null otherwise.
54+
*/
55+
public function getJobId(): ?int
56+
{
57+
return $this->jobId;
58+
}
59+
60+
/**
61+
* Returns the error message if the push failed, null otherwise.
62+
*/
63+
public function getError(): ?string
64+
{
65+
return $this->error;
66+
}
67+
}

‎tests/DatabaseHandlerTest.php‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ public function testPush(): void
8585
$handler = new DatabaseHandler($this->config);
8686
$result = $handler->push('queue', 'success', ['key' => 'value']);
8787

88-
$this->assertTrue($result);
88+
$this->assertTrue($result->getStatus());
8989
$this->seeInDatabase('queue_jobs', [
9090
'queue' => 'queue',
9191
'payload' => json_encode(['job' => 'success', 'data' => ['key' => 'value'], 'metadata' => []]),
@@ -103,7 +103,7 @@ public function testPushWithPriority(): void
103103
$handler = new DatabaseHandler($this->config);
104104
$result = $handler->setPriority('high')->push('queue', 'success', ['key' => 'value']);
105105

106-
$this->assertTrue($result);
106+
$this->assertTrue($result->getStatus());
107107
$this->seeInDatabase('queue_jobs', [
108108
'queue' => 'queue',
109109
'payload' => json_encode(['job' => 'success', 'data' => ['key' => 'value'], 'metadata' => []]),
@@ -122,7 +122,7 @@ public function testPushAndPopWithPriority(): void
122122
$handler = new DatabaseHandler($this->config);
123123
$result = $handler->push('queue', 'success', ['key1' => 'value1']);
124124

125-
$this->assertTrue($result);
125+
$this->assertTrue($result->getStatus());
126126
$this->seeInDatabase('queue_jobs', [
127127
'queue' => 'queue',
128128
'payload' => json_encode(['job' => 'success', 'data' => ['key1' => 'value1'], 'metadata' => []]),
@@ -132,7 +132,7 @@ public function testPushAndPopWithPriority(): void
132132

133133
$result = $handler->setPriority('high')->push('queue', 'success', ['key2' => 'value2']);
134134

135-
$this->assertTrue($result);
135+
$this->assertTrue($result->getStatus());
136136
$this->seeInDatabase('queue_jobs', [
137137
'queue' => 'queue',
138138
'payload' => json_encode(['job' => 'success', 'data' => ['key2' => 'value2'], 'metadata' => []]),
@@ -161,7 +161,7 @@ public function testPushWithDelay(): void
161161
$handler = new DatabaseHandler($this->config);
162162
$result = $handler->setDelay(MINUTE)->push('queue-delay', 'success', ['key' => 'value']);
163163

164-
$this->assertTrue($result);
164+
$this->assertTrue($result->getStatus());
165165

166166
$availableAt = 1703859376;
167167

@@ -188,7 +188,7 @@ public function testChain(): void
188188
->push('queue', 'success', ['key2' => 'value2']);
189189
});
190190

191-
$this->assertTrue($result);
191+
$this->assertTrue($result->getStatus());
192192
$this->seeInDatabase('queue_jobs', [
193193
'queue' => 'queue',
194194
'payload' => json_encode([
@@ -221,7 +221,7 @@ public function testChainWithPriorityAndDelay(): void
221221
->setDelay(120);
222222
});
223223

224-
$this->assertTrue($result);
224+
$this->assertTrue($result->getStatus());
225225
$this->seeInDatabase('queue_jobs', [
226226
'queue' => 'queue',
227227
'payload' => json_encode([

‎tests/Payloads/ChainBuilderTest.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ public function testChainWithSingleJob(): void
6363
$chain->push('queue', 'success', ['key' => 'value']);
6464
});
6565

66-
$this->assertTrue($result);
66+
$this->assertTrue($result->getStatus());
6767
$this->seeInDatabase('queue_jobs', [
6868
'queue' => 'queue',
6969
'payload' => json_encode([
@@ -84,7 +84,7 @@ public function testEmptyChain(): void
8484
// No jobs added
8585
});
8686

87-
$this->assertTrue($result);
87+
$this->assertFalse($result->getStatus());
8888
$this->seeInDatabase('queue_jobs', []);
8989
}
9090

@@ -99,7 +99,7 @@ public function testMultipleDifferentQueues(): void
9999
->push('queue2', 'success', ['key2' => 'value2']);
100100
});
101101

102-
$this->assertTrue($result);
102+
$this->assertTrue($result->getStatus());
103103
$this->seeInDatabase('queue_jobs', [
104104
'queue' => 'queue1',
105105
'payload' => json_encode([
@@ -132,7 +132,7 @@ public function testChainWithManyJobs(): void
132132
->push('queue', 'success', ['key3' => 'value3']);
133133
});
134134

135-
$this->assertTrue($result);
135+
$this->assertTrue($result->getStatus());
136136
$this->seeInDatabase('queue_jobs', [
137137
'queue' => 'queue',
138138
'payload' => json_encode([

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /