Skip to content

Commit 47907c9

Browse files
michalsnmichalsn
committed
docs
1 parent 20017fd commit 47907c9

11 files changed

Lines changed: 459 additions & 0 deletions

‎docs/assets/favicon.ico‎

14.7 KB
Binary file not shown.

‎docs/assets/flame.svg‎

Lines changed: 11 additions & 0 deletions
Loading

‎docs/assets/github-dark-dimmed.css‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
2+
Theme: GitHub Dark Dimmed
3+
Description: Dark dimmed theme as seen on github.com
4+
Author: github.com
5+
Maintainer: @Hirse
6+
Updated: 2021-05-15
7+
Modified: 2022:12:27 by @michalsn
8+
9+
Colors taken from GitHub's CSS
10+
*/.hljs{color:#adbac7 !important;background-color:#22272e !important}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#f47067}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#dcbdfb}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#6cb6ff}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#96d0ff}.hljs-built_in,.hljs-symbol{color:#f69d50}.hljs-code,.hljs-comment,.hljs-formula{color:#768390}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#8ddb8c}.hljs-subst{color:#adbac7}.hljs-section{color:#316dca;font-weight:700}.hljs-bullet{color:#eac55f}.hljs-emphasis{color:#adbac7;font-style:italic}.hljs-strong{color:#adbac7;font-weight:700}.hljs-addition{color:#b4f1b4;background-color:#1b4721}.hljs-deletion{color:#ffd8d3;background-color:#78191b}
11+
12+
[data-md-color-scheme="default"] {
13+
--md-default-fg-color--lightest: #575757;
14+
--md-default-fg-color--light: #959595;
15+
}

‎docs/assets/hljs.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
document.addEventListener('DOMContentLoaded', (ev) => {
2+
hljs.highlightAll();
3+
});

‎docs/basic_usage.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Basic usage
2+
3+
The reason we choose queues is that we want to run jobs in the background.
4+
5+
Here we will present how you can create your own job class, which you will later use in your own queue.
6+
7+
---
8+
9+
- [Create a job class](#creating-a-job-class)
10+
- [Implement a job](#implement-a-job)
11+
- [Sending job to the queue](#sending-job-to-the-queue)
12+
- [Consuming the queue](#consuming-the-queue)
13+
14+
15+
### Create a job class
16+
17+
Here with help comes a generator that will allow us to quickly get started. In our example we will create the `Email` class:
18+
19+
php spark queue:job Email
20+
21+
The above command will create a file in `App\Jobs` namespace. Once we have our class, we need to add it to the `$jobHandlers` array, in the `Config\Queue` configuration file.
22+
23+
```php
24+
// app/Config/Queue.php
25+
26+
// ...
27+
28+
/**
29+
* Your jobs handlers.
30+
*/
31+
public array $jobHandlers = [
32+
'email' => Email::class,
33+
];
34+
35+
// ...
36+
```
37+
38+
### Implement a job
39+
40+
One of the most popular tasks delegated to a queue is sending email messages. Therefore, in this example, we will just implement that.
41+
42+
```php
43+
<?php
44+
45+
namespace App\Jobs;
46+
47+
use Exception;
48+
use Michalsn\CodeIgniterQueue\BaseJob;
49+
use Michalsn\CodeIgniterQueue\Interfaces\JobInterface;
50+
51+
class Email extends BaseJob implements JobInterface
52+
{
53+
/**
54+
* @throws Exception
55+
*/
56+
public function process()
57+
{
58+
$email = service('email', null, false);
59+
$result = $email
60+
->setTo('test@email.test')
61+
->setSubject('My test email')
62+
->setMessage($this->data['message'])
63+
->send(false);
64+
65+
if (! $result) {
66+
throw new Exception($email->printDebugger('headers'));
67+
}
68+
69+
return $result;
70+
}
71+
}
72+
```
73+
74+
The method that handles the job is the `process` method. It is the one that is called when our job is executed.
75+
76+
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.
77+
78+
### Sending job to the queue
79+
80+
Sending a task to the queue is very simple and comes down to a call:
81+
82+
```php
83+
service('queue')->push('QueueName', 'jobName', ['array' => 'parameters']);
84+
```
85+
86+
In our particular case, for the Email class, it might look like this:
87+
88+
```php
89+
service('queue')->push('emails', 'email', ['message' => 'Email message goes here']);
90+
```
91+
92+
That's it, we just added our Email job to the queue.
93+
94+
### Consuming the queue
95+
96+
Since we sent our sample job to queue `emails`, then we need to run the worker with the appropriate queue:
97+
98+
php spark queue:work emails
99+
100+
Now we are going to consume jobs from the queue `emails`. This command has many parameters, but you can learn more about that at [commands](commands.md) page.

‎docs/commands.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Commands
2+
3+
Here are all the commands you can use with the Queue library.
4+
5+
---
6+
7+
Available options:
8+
9+
- [queue:publish](#queuePublish)
10+
- [queue:job](#queueJob)
11+
- [queue:work](#queueWork)
12+
- [queue:stop](#queueStop)
13+
- [queue:clear](#queueClear)
14+
- [queue:failed](#queueFailed)
15+
- [queue:retry](#queueRetry)
16+
- [queue:forget](#queueForget)
17+
- [queue:flush](#queueFlush)
18+
19+
20+
### queue:publish
21+
22+
Allows you to publish a configuration class in the application namespace.
23+
24+
#### Example
25+
26+
php spark queue:publish
27+
28+
### queue:job
29+
30+
Generates a new job file.
31+
32+
#### Arguments
33+
34+
* `name` - The job class name.
35+
36+
#### Options
37+
38+
* `--namespace` - Set root namespace. Default: "APP_NAMESPACE".
39+
* `--suffix` - Append the component title to the class name (e.g. Email => EmailJob).
40+
* `--force` - Force overwrite existing file.
41+
42+
#### Example
43+
44+
php spark queue:job Email
45+
46+
It will generate the `Email` class in the `App\Jobs` namespace.
47+
48+
### queue:work
49+
50+
Allows you to consume jobs from a specific queue.
51+
52+
#### Arguments
53+
54+
* `queueName` - Name of the queue we will work with.
55+
56+
#### Options
57+
58+
* `-sleep` - Wait time between the next check for available job when the queue is empty. Default value: `10` (seconds).
59+
* `-rest` - Rest time between the jobs in the queue. Default value: `0` (seconds)
60+
* `-max-jobs` - The maximum number of jobs to handle before worker should exit. Disabled by default.
61+
* `-max-time` - The maximum number of seconds worker should run. Disabled by default.
62+
* `-memory` - The maximum memory in MB that worker can take. Default value: `128`,
63+
* `-tries` - The number of attempts after which the job will be considered as failed. Overrides settings from the Job class. Disabled by default.
64+
* `-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.
65+
* `--stop-when-empty` - Stop when the queue is empty.
66+
67+
#### Example
68+
69+
php spark queue:work emails -max-jobs 5
70+
71+
It will listen for 5 jobs from the `emails` queue and then stop.
72+
73+
### queue:stop
74+
75+
Allows you to stop a specific queue in a safe way. It does this as soon as the job that is running in the queue is completed.
76+
77+
#### Arguments
78+
79+
* `queueName` - Name of the queue we will work with.
80+
81+
#### Example
82+
83+
php spark queue:stop emails
84+
85+
### queue:clear
86+
87+
Allows you to remove all jobs from a specific queue.
88+
89+
#### Arguments
90+
91+
* `queueName` - Name of the queue we will work with.
92+
93+
#### Example
94+
95+
php spark queue:clear emails
96+
97+
### queue:failed
98+
99+
Allows you to view all failed jobs. Also only from a specific queue
100+
101+
#### Options
102+
103+
* `-queue` - Queue name.
104+
105+
#### Example
106+
107+
php spark queue:failed -queue emails
108+
109+
It will list failed jobs from the `emails` queue.
110+
111+
### queue:retry
112+
113+
Allows you to retry failed jobs back to the queue.
114+
115+
#### Arguments
116+
117+
* `id` - ID of the failed job or "all" for all failed jobs.
118+
119+
#### Options
120+
121+
* `-queue` - Queue name.
122+
123+
#### Example
124+
125+
php spark queue:retry all -queue emails
126+
127+
It will retry all the failed jobs from the `emails` queue.
128+
129+
### queue:forget
130+
131+
Allows you to delete the failed job by ID
132+
133+
#### Arguments
134+
135+
* `id` - ID of the failed job.
136+
137+
#### Example
138+
139+
php spark queue:forget 123
140+
141+
### queue:flush
142+
143+
Allows you to delete many failed jobs at once. Based on the failed date and queue.
144+
145+
#### Options
146+
147+
* `-hours` - Number of hours.
148+
* `-queue` - Queue name.
149+
150+
#### Example
151+
152+
php spark queue:flush -hours 6
153+
154+
It will delete all failed jobs older than 6 hours.

‎docs/configuration.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Configuration
2+
3+
To make changes to the config file, we have to have our copy in the `app/Config/Queue.php`. Luckily, this package comes with handy command that will make this easy.
4+
5+
When we run:
6+
7+
php spark queue:publish
8+
9+
We will get our copy ready for modifications.
10+
11+
---
12+
13+
Available options:
14+
15+
- [$defaultHandler](#defaultHandler)
16+
- [$handlers](#handlers)
17+
- [$database](#database)
18+
- [$keepDoneJobs](#keepDoneJobs)
19+
- [$keepFailedJobs](#keepFailedJobs)
20+
- [$jobHandlers](#jobHandlers)
21+
22+
### $defaultHandler
23+
24+
The default handler used by the library. Default value: `database`.
25+
26+
### $handlers
27+
28+
An array of available handlers. By now only `database` handler is implemented.
29+
30+
### $database
31+
32+
The configuration settings for `database` handler.
33+
34+
* `dbGroup` - The database group to use. Default value: `default`.
35+
* `getShared` - Weather to use shared instance. Default value: `true`.
36+
37+
### $keepDoneJobs
38+
39+
If the job is done, should we keep it in the table? Default value: `false`.
40+
41+
### $keepFailedJobs
42+
43+
If the job failed, should we move it to the failed jobs table? Default value: `true`.
44+
45+
This is very useful when you want to be able to see which tasks are failing and why.
46+
47+
### $jobHandlers
48+
49+
An array of available jobs as key-value. Every job that you want to use with the queue has to be defined here.
50+
51+
The key of the array is used to recognize the job, when we push it to the queue.
52+
53+
Example:
54+
55+
```php
56+
public array $jobHandlers = [
57+
'email' => Email::class,
58+
];
59+
```

‎docs/index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# CodeIgniter Queue Documentation
2+
3+
A library that helps you handle Queues in the CodeIgniter 4 framework.
4+
5+
Add job to the queue.
6+
```php
7+
service('queue')->push('QueueName', 'jobName', ['array' => 'parameters']);
8+
```
9+
10+
Listen for queue jobs.
11+
12+
php spark queue:work QueueName
13+
14+
### Requirements
15+
16+
![PHP](https://img.shields.io/badge/PHP-%5E8.1-blue)
17+
![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.3-blue)
18+
19+
### Table of Contents
20+
21+
* [Installation](installation.md)
22+
* [Configuration](configuration.md)
23+
* [Basic usage](basic_usage.md)
24+
* [Running queues](running_queues.md)
25+
* [Commands](commands.md)
26+
* [Troubleshooting](troubleshooting.md)

0 commit comments

Comments
 (0)