Skip to content

Commit

Permalink
docs update
Browse files Browse the repository at this point in the history
  • Loading branch information
michalsn committed Oct 15, 2023
1 parent 8aa33e1 commit c3207e2
Show file tree
Hide file tree
Showing 6 changed files with 33 additions and 15 deletions.
23 changes: 21 additions & 2 deletions docs/basic_usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 4 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 4 additions & 8 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
2 changes: 2 additions & 0 deletions docs/running_queues.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit c3207e2

Please sign in to comment.