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
2020use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
2121
22- // Dispatch a simple closure task
22+ // Dispatch a simple closure job
2323dispatch(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
3232use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
3333
3434// Set maximum attempts (retry limit)
3535dispatch(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
4848use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
4949
5050// Chain multiple configuration options
5151dispatch(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
6464use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
6565
66- // Use specified queue connection
66+ // Use a specific queue connection
6767dispatch(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
7272dispatch(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
8282use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
8383
84- // Execute after 60 seconds delay
84+ // Delay execution by 60 seconds
8585dispatch(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
9090dispatch(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
100100use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
@@ -103,23 +103,23 @@ $isUrgent = true;
103103
104104// Execute callback only when condition is true
105105dispatch(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
113113dispatch(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
121121dispatch(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
137137use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
@@ -142,9 +142,9 @@ use Psr\Log\LoggerInterface;
142142dispatch(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
163163dispatch(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
187187use 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
236238Set 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
276274Execute 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
287287Execute 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 [
340342composer 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
349351class 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
369371use function FriendsOfHyperf\AsyncQueueClosureJob\dispatch;
370372
371- // Use closure directly , no need to create class
373+ // Directly use closure , no need to create a class
372374dispatch(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