docs

Author: michalsn

docs/assets/favicon.ico

@@ -0,0 +1,15 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub Dark Dimmed
+  Description: Dark dimmed theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+  Modified: 2022:12:27 by @michalsn
+
+  Colors taken from GitHub's CSS
+*/.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}
+
+[data-md-color-scheme="default"] {
+    --md-default-fg-color--lightest: #575757;
+    --md-default-fg-color--light: #959595;
+}

docs/assets/flame.svg

@@ -0,0 +1,3 @@
+document.addEventListener('DOMContentLoaded', (ev) => {
+    hljs.highlightAll();
+});

docs/assets/github-dark-dimmed.css

@@ -0,0 +1,100 @@
+# Basic usage
+
+The reason we choose queues is that we want to run jobs in the background.
+
+Here we will present how you can create your own job class, which you will later use in your own queue.
+
+---
+
+- [Create a job class](#creating-a-job-class)
+- [Implement a job](#implement-a-job)
+- [Sending job to the queue](#sending-job-to-the-queue)
+- [Consuming the queue](#consuming-the-queue)
+
+
+### Create a job class
+
+Here with help comes a generator that will allow us to quickly get started. In our example we will create the `Email` class:
+
+    php spark queue:job Email
+
+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.
+
+```php
+// app/Config/Queue.php
+
+// ...
+
+/**
+ * Your jobs handlers.
+ */
+public array $jobHandlers = [
+    'email' => Email::class,
+];
+
+// ...
+```
+
+### Implement a job
+
+One of the most popular tasks delegated to a queue is sending email messages. Therefore, in this example, we will just implement that.
+
+```php
+<?php
+
+namespace App\Jobs;
+
+use Exception;
+use Michalsn\CodeIgniterQueue\BaseJob;
+use Michalsn\CodeIgniterQueue\Interfaces\JobInterface;
+
+class Email extends BaseJob implements JobInterface
+{
+    /**
+     * @throws Exception
+     */
+    public function process()
+    {
+        $email  = service('email', null, false);
+        $result = $email
+            ->setTo('[email protected]')
+            ->setSubject('My test email')
+            ->setMessage($this->data['message'])
+            ->send(false);
+
+        if (! $result) {
+            throw new Exception($email->printDebugger('headers'));
+        }
+
+        return $result;
+    }
+}
+```
+
+The method that handles the job is the `process` method. It is the one that 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.
+
+### Sending job to the queue
+
+Sending a task to the queue is very simple and comes down to a call:
+
+```php
+service('queue')->push('QueueName', 'jobName', ['array' => 'parameters']);
+```
+
+In our particular case, for the Email class, it might look like this:
+
+```php
+service('queue')->push('emails', 'email', ['message' => 'Email message goes here']);
+```
+
+That's it, we just added our Email job to the queue.
+
+### Consuming the queue
+
+Since we sent our sample job to queue `emails`, then we need to run the worker with the appropriate queue:
+
+    php spark queue:work emails
+
+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/assets/hljs.js

@@ -0,0 +1,154 @@
+# Commands
+
+Here are all the commands you can use with the Queue library.
+
+---
+
+Available options:
+
+- [queue:publish](#queuePublish)
+- [queue:job](#queueJob)
+- [queue:work](#queueWork)
+- [queue:stop](#queueStop)
+- [queue:clear](#queueClear)
+- [queue:failed](#queueFailed)
+- [queue:retry](#queueRetry)
+- [queue:forget](#queueForget)
+- [queue:flush](#queueFlush)
+
+
+### queue:publish
+
+Allows you to publish a configuration class in the application namespace.
+
+#### Example
+
+    php spark queue:publish
+
+### queue:job
+
+Generates a new job file.
+
+#### Arguments
+
+* `name` - The job class name.
+
+#### Options
+
+* `--namespace` - Set root namespace. Default: "APP_NAMESPACE".
+* `--suffix` - Append the component title to the class name (e.g. Email => EmailJob).
+* `--force` - Force overwrite existing file.
+
+#### Example
+
+    php spark queue:job Email
+
+It will generate the `Email` class in the `App\Jobs` namespace.
+
+### queue:work
+
+Allows you to consume jobs from a specific queue.
+
+#### Arguments
+
+* `queueName` - Name of the queue we will work with.
+
+#### Options
+
+* `-sleep` - Wait time between the next check for available job when the queue is empty. Default value: `10` (seconds).
+* `-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`,
+* `-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.
+
+#### Example
+
+    php spark queue:work emails -max-jobs 5
+
+It will listen for 5 jobs from the `emails` queue and then stop.
+
+### queue:stop
+
+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.
+
+#### Arguments
+
+* `queueName` - Name of the queue we will work with.
+
+#### Example
+
+    php spark queue:stop emails
+
+### queue:clear
+
+Allows you to remove all jobs from a specific queue.
+
+#### Arguments
+
+* `queueName` - Name of the queue we will work with.
+
+#### Example
+
+    php spark queue:clear emails
+
+### queue:failed
+
+Allows you to view all failed jobs. Also only from a specific queue
+
+#### Options
+
+* `-queue` - Queue name.
+
+#### Example
+
+    php spark queue:failed -queue emails
+
+It will list failed jobs from the `emails` queue.
+
+### queue:retry
+
+Allows you to retry failed jobs back to the queue.
+
+#### Arguments
+
+* `id` - ID of the failed job or "all" for all failed jobs.
+
+#### Options
+
+* `-queue` -  Queue name.
+
+#### Example
+
+    php spark queue:retry all -queue emails
+
+It will retry all the failed jobs from the `emails` queue.
+
+### queue:forget
+
+Allows you to delete the failed job by ID
+
+#### Arguments
+
+* `id` - ID of the failed job.
+
+#### Example
+
+    php spark queue:forget 123
+
+### queue:flush
+
+Allows you to delete many failed jobs at once. Based on the failed date and queue.
+
+#### Options
+
+* `-hours` - Number of hours.
+* `-queue` - Queue name.
+
+#### Example
+
+    php spark queue:flush -hours 6
+
+It will delete all failed jobs older than 6 hours.

docs/basic_usage.md

@@ -0,0 +1,59 @@
+# Configuration
+
+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.
+
+When we run:
+
+    php spark queue:publish
+
+We will get our copy ready for modifications.
+
+---
+
+Available options:
+
+- [$defaultHandler](#defaultHandler)
+- [$handlers](#handlers)
+- [$database](#database)
+- [$keepDoneJobs](#keepDoneJobs)
+- [$keepFailedJobs](#keepFailedJobs)
+- [$jobHandlers](#jobHandlers)
+
+### $defaultHandler
+
+The default handler used by the library. Default value: `database`.
+
+### $handlers
+
+An array of available handlers. By now only `database` handler is implemented.
+
+### $database
+
+The configuration settings for `database` handler.
+
+* `dbGroup` - The database group to use. Default value: `default`.
+* `getShared` - Weather to use shared instance. Default value: `true`.
+
+### $keepDoneJobs
+
+If the job is done, should we keep it in the table? Default value: `false`.
+
+### $keepFailedJobs
+
+If the job failed, should we move it to the failed jobs table? Default value: `true`.
+
+This is very useful when you want to be able to see which tasks are failing and why.
+
+### $jobHandlers
+
+An array of available jobs as key-value. Every job that you want to use with the queue has to be defined here.
+
+The key of the array is used to recognize the job, when we push it to the queue.
+
+Example:
+
+```php
+public array $jobHandlers = [
+    'email' => Email::class,
+];
+```

docs/commands.md

@@ -0,0 +1,26 @@
+# CodeIgniter Queue Documentation
+
+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']);
+```
+
+Listen for queue jobs.
+
+    php spark queue:work QueueName
+
+### Requirements
+
+![PHP](https://img.shields.io/badge/PHP-%5E8.1-blue)
+![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.3-blue)
+
+### Table of Contents
+
+* [Installation](installation.md)
+* [Configuration](configuration.md)
+* [Basic usage](basic_usage.md)
+* [Running queues](running_queues.md)
+* [Commands](commands.md)
+* [Troubleshooting](troubleshooting.md)