From c3207e2c060abdea76555440fdbe9e41b22581a0 Mon Sep 17 00:00:00 2001 From: michalsn Date: Sun, 15 Oct 2023 09:07:19 +0200 Subject: [PATCH] docs update --- docs/basic_usage.md | 23 +++++++++++++++++++++-- docs/commands.md | 2 +- docs/index.md | 7 ++++--- docs/installation.md | 12 ++++-------- docs/running_queues.md | 2 ++ docs/troubleshooting.md | 2 +- 6 files changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/basic_usage.md b/docs/basic_usage.md index 6a2dffb..16f2f42 100644 --- a/docs/basic_usage.md +++ b/docs/basic_usage.md @@ -73,18 +73,37 @@ class Email extends BaseJob implements JobInterface } ``` -The method that handles the job is the `process` method. It is the one that is called when our job is executed. +To handles the job we always use the `process` method. This method is called when our job is executed. You may be wondering what the `$this->data['message']` variable is all about. We'll explain that in detail in the next section, but for now it's important for you to remember that all the variables we pass to the Job class are always held in the `$this->data` variable. Throwing an exception is a way to let the queue worker know that the job has failed. +We can also configure some things on the job level. It's a number of tries, when the job is failing and time after the job will be retried again after failure. We can specify these options by using variables: + +```php +// ... + +class Email extends BaseJob implements JobInterface +{ + protected int $retryAfter = 60; + protected int $tries = 1; + + // ... + +} +``` + +Values presented above, are the default one. So you need to add them only when you want to change them. + +These variables may be overwritten by the queue worker, if we use the proper parameters with command `queue:work`. For more information, see [commands](commands.md). + ### Sending job to the queue Sending a task to the queue is very simple and comes down to one command: ```php -service('queue')->push('QueueName', 'jobName', ['array' => 'parameters']); +service('queue')->push('queueName', 'jobName', ['array' => 'parameters']); ``` In our particular case, for the `Email` class, it might look like this: diff --git a/docs/commands.md b/docs/commands.md index c6b017e..bb7c0d5 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -59,7 +59,7 @@ Allows you to consume jobs from a specific queue. * `-rest` - Rest time between the jobs in the queue. Default value: `0` (seconds) * `-max-jobs` - The maximum number of jobs to handle before worker should exit. Disabled by default. * `-max-time` - The maximum number of seconds worker should run. Disabled by default. -* `-memory` - The maximum memory in MB that worker can take. Default value: `128`, +* `-memory` - The maximum memory in MB that worker can take. Default value: `128`. * `-tries` - The number of attempts after which the job will be considered as failed. Overrides settings from the Job class. Disabled by default. * `-retry-after` - The number of seconds after which the job is to be restarted in case of failure. Overrides settings from the Job class. Disabled by default. * `--stop-when-empty` - Stop when the queue is empty. diff --git a/docs/index.md b/docs/index.md index a7bbff5..1434981 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,13 +3,14 @@ A library that helps you handle Queues in the CodeIgniter 4 framework. Add job to the queue. + ```php -service('queue')->push('QueueName', 'jobName', ['array' => 'parameters']); +service('queue')->push('queueName', 'jobName', ['array' => 'parameters']); ``` -Listen for queue jobs. +Listen for queued jobs. - php spark queue:work QueueName + php spark queue:work queueName ### Requirements diff --git a/docs/installation.md b/docs/installation.md index 69f767c..daf7973 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,15 +2,13 @@ - [Composer Installation](#composer-installation) - [Manual Installation](#manual-installation) -- [Database migration](#database-migration) +- [Database Migration](#database-migration) ## Composer Installation The only thing you have to do is to run this command, and you're ready to go. -```console -composer require michalsn/codeigniter-queue -``` + composer require michalsn/codeigniter-queue ## Manual Installation @@ -32,12 +30,10 @@ public $psr4 = [ // ... ``` -## Database migration +## Database Migration Regardless of which installation method you chose, we also need to migrate the database to add new tables. You can do this with the following command: -```console -php spark migrate --all -``` + php spark migrate --all diff --git a/docs/running_queues.md b/docs/running_queues.md index 1c3dbf6..b55d99b 100644 --- a/docs/running_queues.md +++ b/docs/running_queues.md @@ -26,6 +26,8 @@ We could think about resigning with `-max-jobs` parameter, but it can have unpre So choosing the right command is not so obvious. We have to estimate how many jobs we will have in the queue and decide how crucial it is to empty the queue as soon as possible. +You might use CodeIgniter [Tasks](https://github.com/codeigniter4/tasks) library to schedule queue worker instead of working directly with CRON. + ### Running many instances of the same queue As mentioned above, sometimes we may want to have multiple instances of the same command running at the same time. The queue is safe to use in that scenario with all databases except `SQLite3` since it doesn't guarantee that the job will be selected only by one process. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d43b300..58d91bc 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,4 +4,4 @@ If you want to assign an object to the queue, please make sure it implements `JsonSerializable` interface. This is how CodeIgniter [Entities](https://codeigniter.com/user_guide/models/entities.html) are handled by default. -You may ask, why not just use `serialize` and `unserialize`? There are security reasons that keep us from doing so. These methods are not safe to use with user provided data. +You may ask, why not just use `serialize` and `unserialize`? There are security reasons that keep us from doing so. These functions are not safe to use with user provided data.