Skip to content

Commit b256c29

Browse files
committed
Update async queue job docs to use onPool method
Replaces references and documentation for the onConnection method with onPool in all language versions. Clarifies that onPool sets the queue connection name and removes duplicate/alias documentation for consistency.
1 parent 63b4176 commit b256c29

4 files changed

Lines changed: 78 additions & 105 deletions

File tree

docs/en/components/async-queue-closure-job.md

Lines changed: 75 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
## Introduction
44

5-
`friendsofhyperf/async-queue-closure-job` is an asynchronous queue closure job component for Hyperf. It allows you to execute closures as background tasks, with full support for dependency injection and fluent configuration, making the use of asynchronous tasks simpler and more elegant.
5+
`friendsofhyperf/async-queue-closure-job` is an async queue closure job component for Hyperf. It allows you to execute closures as background jobs with full support for dependency injection and fluent configuration, making async tasks simpler and more elegant.
66

7-
Unlike the traditional approach of creating task classes, this component enables you to define task logic directly using closures, eliminating the need for additional class files and making the code more concise.
7+
Unlike traditional job classes, this component lets you define job logic directly with closures, eliminating the need for extra class files and making your code more concise.
88

99
## Installation
1010

@@ -14,26 +14,26 @@ composer require friendsofhyperf/async-queue-closure-job
1414

1515
## Basic Usage
1616

17-
### Simple Closure Task
17+
### Simple Closure Job
1818

1919
```php
2020
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
2121

22-
// Dispatch a simple closure task
22+
// Dispatch a simple closure job
2323
dispatch(function () {
24-
// Your task logic
24+
// Your job logic here
2525
var_dump('Hello from closure job!');
2626
});
2727
```
2828

29-
### Setting Maximum Attempts
29+
### Set Maximum Attempts
3030

3131
```php
3232
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
3333

3434
// Set maximum attempts (retry limit)
3535
dispatch(function () {
36-
// Your task logic
36+
// Your job logic here
3737
// If it fails, it will retry up to 3 times
3838
})->setMaxAttempts(3);
3939
```
@@ -42,59 +42,59 @@ dispatch(function () {
4242

4343
### Fluent API Configuration
4444

45-
You can flexibly configure various task options through method chaining:
45+
You can flexibly configure various options using method chaining:
4646

4747
```php
4848
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
4949

5050
// Chain multiple configuration options
5151
dispatch(function () {
52-
// Your task logic
52+
// Your job logic here
5353
})
5454
->onPool('high-priority') // Specify queue connection
5555
->delay(60) // Delay execution by 60 seconds
56-
->setMaxAttempts(5); // Maximum of 5 retries
56+
->setMaxAttempts(5); // Retry up to 5 times
5757
```
5858

59-
### Specifying Queue Connection
59+
### Specifying Queue Connections
6060

61-
When you have multiple queue connections, you can specify which connection the task uses:
61+
When you have multiple queue connections, you can specify which connection to use:
6262

6363
```php
6464
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
6565

66-
// Use specified queue connection
66+
// Use a specific queue connection
6767
dispatch(function () {
68-
// High-priority task logic
68+
// High priority task logic
6969
})->onPool('high-priority');
7070

71-
// Or use the onPool method (alias)
71+
// Alternative pool name
7272
dispatch(function () {
73-
// Low-priority task logic
73+
// Low priority task logic
7474
})->onPool('low-priority');
7575
```
7676

7777
### Delayed Execution
7878

79-
You can set tasks to execute after a certain period:
79+
You can set a delay before the task starts executing:
8080

8181
```php
8282
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
8383

84-
// Execute after 60 seconds delay
84+
// Delay execution by 60 seconds
8585
dispatch(function () {
86-
// Your task logic
86+
// Your job logic here
8787
})->delay(60);
8888

89-
// Execute after 5 minutes delay
89+
// Delay execution by 5 minutes
9090
dispatch(function () {
91-
// Your task logic
91+
// Your job logic here
9292
})->delay(300);
9393
```
9494

9595
### Conditional Execution
9696

97-
Use the `when` and `unless` methods to dynamically configure tasks based on conditions:
97+
Use `when` and `unless` methods to dynamically configure tasks based on conditions:
9898

9999
```php
100100
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
@@ -103,23 +103,23 @@ $isUrgent = true;
103103

104104
// Execute callback only when condition is true
105105
dispatch(function () {
106-
// Your task logic
106+
// Your job logic here
107107
})
108108
->when($isUrgent, function ($dispatch) {
109109
$dispatch->onPool('urgent');
110110
});
111111

112112
// Execute callback only when condition is false
113113
dispatch(function () {
114-
// Your task logic
114+
// Your job logic here
115115
})
116116
->unless($isUrgent, function ($dispatch) {
117-
$dispatch->delay(300);
117+
$dispatch->delay(30);
118118
});
119119

120-
// Combined usage
120+
// Combine usage
121121
dispatch(function () {
122-
// Your task logic
122+
// Your job logic here
123123
})
124124
->when($isUrgent, function ($dispatch) {
125125
$dispatch->onPool('urgent');
@@ -131,7 +131,7 @@ dispatch(function () {
131131

132132
### Dependency Injection
133133

134-
Closure tasks fully support Hyperf's dependency injection functionality. You can declare required dependencies in the closure parameters:
134+
Closure jobs fully support Hyperf's dependency injection. You can declare required dependencies as closure parameters:
135135

136136
```php
137137
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
@@ -142,9 +142,9 @@ use Psr\Log\LoggerInterface;
142142
dispatch(function (UserService $userService, LoggerInterface $logger) {
143143
$users = $userService->getActiveUsers();
144144
$logger->info('Processing ' . count($users) . ' users');
145-
145+
146146
foreach ($users as $user) {
147-
// Process user...
147+
// Process users...
148148
}
149149
});
150150
```
@@ -162,14 +162,14 @@ $action = 'update';
162162
// Use captured variables
163163
dispatch(function (UserService $userService) use ($userId, $action) {
164164
$user = $userService->find($userId);
165-
165+
166166
if ($action === 'update') {
167167
$userService->update($user);
168168
}
169169
})->setMaxAttempts(3);
170170
```
171171

172-
## Practical Application Scenarios
172+
## Real-World Use Cases
173173

174174
### Sending Notifications
175175

@@ -181,7 +181,7 @@ dispatch(function (NotificationService $notification) use ($userId, $message) {
181181
})->setMaxAttempts(3);
182182
```
183183

184-
### Processing File Uploads
184+
### File Upload Processing
185185

186186
```php
187187
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
@@ -221,103 +221,105 @@ foreach ($userIds as $userId) {
221221

222222
### `dispatch(Closure $closure): PendingAsyncQueueDispatch`
223223

224-
The main dispatch function used to create closure tasks.
224+
The main dispatch function that creates a closure job.
225225

226226
**Parameters:**
227+
227228
- `$closure` - The closure to execute
228229

229230
**Returns:**
231+
230232
- `PendingAsyncQueueDispatch` - Pending closure dispatch object
231233

232234
### `PendingAsyncQueueDispatch` Methods
233235

234-
#### `onPool(string $connection): static`
236+
#### `onPool(string $pool): static`
235237

236238
Set the queue connection name.
237239

238240
**Parameters:**
239-
- `$connection` - Queue connection name
240241

241-
**Returns:**
242-
- `static` - Current object, supports method chaining
243-
244-
#### `onPool(string $pool): static`
245-
246-
Set the queue connection name (alias of `onPool`).
247-
248-
**Parameters:**
249242
- `$pool` - Queue connection name
250243

251244
**Returns:**
252-
- `static` - Current object, supports method chaining
245+
246+
- `static` - Current object for method chaining
253247

254248
#### `delay(int $delay): static`
255249

256-
Set the delay execution time.
250+
Set the delay time before execution.
257251

258252
**Parameters:**
253+
259254
- `$delay` - Delay time in seconds
260255

261256
**Returns:**
262-
- `static` - Current object, supports method chaining
257+
258+
- `static` - Current object for method chaining
263259

264260
#### `setMaxAttempts(int $maxAttempts): static`
265261

266-
Set the maximum number of retry attempts.
262+
Set the maximum retry attempts.
267263

268264
**Parameters:**
269-
- `$maxAttempts` - Maximum number of attempts
265+
266+
- `$maxAttempts` - Maximum attempts
270267

271268
**Returns:**
272-
- `static` - Current object, supports method chaining
269+
270+
- `static` - Current object for method chaining
273271

274272
#### `when($condition, $callback): static`
275273

276274
Execute callback when condition is true.
277275

278276
**Parameters:**
277+
279278
- `$condition` - Condition expression
280279
- `$callback` - Callback function that receives the current object as parameter
281280

282281
**Returns:**
283-
- `static` - Current object, supports method chaining
282+
283+
- `static` - Current object for method chaining
284284

285285
#### `unless($condition, $callback): static`
286286

287287
Execute callback when condition is false.
288288

289289
**Parameters:**
290+
290291
- `$condition` - Condition expression
291292
- `$callback` - Callback function that receives the current object as parameter
292293

293294
**Returns:**
294-
- `static` - Current object, supports method chaining
295+
296+
- `static` - Current object for method chaining
295297

296298
## Supported Closure Types
297299

298-
This component supports the following types of closures:
300+
This component supports the following closure types:
299301

300302
- ✅ Simple closures without parameters
301303
- ✅ Closures with dependency injection
302-
- ✅ Closures using captured variables (`use`)
304+
- ✅ Closures with captured variables (`use`)
303305
- ✅ Closures with nullable parameters
304-
-Closures mixing dependency injection and captured variables
306+
-Mixing dependency injection and captured variables
305307

306308
## Notes
307309

308-
1. **Serialization Limitations**: Closures are serialized for storage, therefore:
309-
- Cannot capture unserializable resources (such as database connections, file handles, etc.)
310+
1. **Serialization Limitations**: Closures are serialized before storage, therefore:
311+
- Cannot capture non-serializable resources (e.g., database connections, file handles)
310312
- Captured objects should be serializable
311313

312-
2. **Dependency Injection**: Dependencies in closures are resolved from the container when the task executes and are not serialized
314+
2. **Dependency Injection**: Dependencies in closures will be resolved from the container when the job executes, not serialized
313315

314-
3. **Asynchronous Execution**: Tasks are executed asynchronously; the dispatch function returns immediately without waiting for task completion
316+
3. **Async Execution**: Tasks execute asynchronously. The dispatch function returns immediately without waiting for task completion
315317

316-
4. **Error Handling**: Failed task executions will retry according to the number of attempts set by `setMaxAttempts`
318+
4. **Error Handling**: Failed tasks will retry according to the `setMaxAttempts` configuration
317319

318320
## Configuration
319321

320-
This component uses Hyperf's asynchronous queue configuration. You can configure queue parameters in `config/autoload/async_queue.php`:
322+
This component uses Hyperf's async queue configuration. You can configure queue parameters in `config/autoload/async_queue.php`:
321323

322324
```php
323325
<?php
@@ -340,12 +342,12 @@ return [
340342
composer test:unit -- tests/AsyncQueueClosureJob
341343
```
342344

343-
## Comparison with Traditional Task Classes
345+
## Comparison with Traditional Job Classes
344346

345347
### Traditional Approach
346348

347349
```php
348-
// Need to create task class
350+
// Need to create a job class
349351
class SendNotificationJob extends Job
350352
{
351353
public function __construct(public int $userId, public string $message)
@@ -359,28 +361,29 @@ class SendNotificationJob extends Job
359361
}
360362
}
361363

362-
// Dispatch task
364+
// Dispatch job
363365
$driver->push(new SendNotificationJob($userId, $message));
364366
```
365367

366-
### Using Closure Tasks
368+
### Using Closure Jobs
367369

368370
```php
369371
use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
370372

371-
// Use closure directly, no need to create class
373+
// Directly use closure, no need to create a class
372374
dispatch(function (NotificationService $notification) use ($userId, $message) {
373375
$notification->send($userId, $message);
374376
});
375377
```
376378

377-
Advantages of closure tasks:
378-
- More concise code, no need for additional class files
379-
- Better readability, task logic is located where it's dispatched
380-
- Full support for dependency injection
379+
Advantages of closure jobs:
380+
381+
- Cleaner code, no need to create extra class files
382+
- Better readability, job logic is right where it's dispatched
383+
- Full dependency injection support
381384
- Flexible fluent API configuration
382385

383386
## Related Components
384387

385-
- [hyperf/async-queue](https://hyperf.wiki/3.1/#/en/async-queue) - Hyperf Async Queue
386-
- [friendsofhyperf/closure-job](https://github.com/friendsofhyperf/components/tree/main/src/closure-job) - General Closure Job Component
388+
- [hyperf/async-queue](https://hyperf.wiki/3.1/#/zh-cn/async-queue) - Hyperf Async Queue
389+
- [friendsofhyperf/closure-job](https://github.com/friendsofhyperf/components/tree/main/src/closure-job) - Generic Closure Job Component

0 commit comments

Comments
 (0)