diff --git a/README.md b/README.md
index 5755c3ff..6089da18 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,11 @@
- 
+ 
-
Yii Queue Extension
+ Yii Queue
-An extension for running tasks asynchronously via queues.
-
-Documentation is at [docs/guide/README.md](docs/guide/README.md).
-
[](https://packagist.org/packages/yiisoft/queue)
[](https://packagist.org/packages/yiisoft/queue)
[](https://github.com/yiisoft/queue/actions)
@@ -19,29 +15,26 @@ Documentation is at [docs/guide/README.md](docs/guide/README.md).
[](https://github.com/yiisoft/queue/actions?query=workflow%3A%22static+analysis%22)
[](https://shepherd.dev/github/yiisoft/queue)
-## Installation
+An extension for running tasks asynchronously via queues.
-The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
+## Requirements
-Either run
+- PHP 8.1 or higher.
-```shell
-composer require yiisoft/queue
-```
+## Installation
-or add
+The package could be installed with [Composer](https://getcomposer.org):
+```shell
+composer require yiisoft/queue
```
-"yiisoft/queue": "~3.0"
-```
-
-to the `require` section of your `composer.json` file.
## Ready for yiisoft/config
If you are using [yiisoft/config](https://github.com/yiisoft/config), you'll find out this package has some defaults
in the [`common`](config/di.php) and [`params`](config/params.php) configurations saving your time. Things you should
change to start working with the queue:
+
- Optionally: define default `\Yiisoft\Queue\Adapter\AdapterInterface` implementation.
- And/or define channel-specific `AdapterInterface` implementations in the `channel-definitions` params key to be used
with the [queue factory](#different-queue-channels).
@@ -53,7 +46,7 @@ change to start working with the queue:
If you have experience with `yiisoft/yii2-queue`, you will find out that this package is similar.
Though, there are some key differences which are described in the "[migrating from yii2-queue](docs/guide/migrating-from-yii2-queue.md)" article.
-## Basic Usage
+## General usage
Each queue task consists of two parts:
@@ -215,6 +208,7 @@ twice for a queue message. That means you can add extra functionality on message
of the two classes: `PushMiddlewareDispatcher` and `ConsumeMiddlewareDispatcher` respectively.
You can use any of these formats to define a middleware:
+
- A ready-to-use middleware object: `new FooMiddleware()`. It must implement `MiddlewarePushInterface`,
`MiddlewareConsumeInterface` or `MiddlewareFailureInterface` depending on the place you use it.
- An array in the format of [yiisoft/definitions](https://github.com/yiisoft/definitions).
@@ -225,6 +219,7 @@ You can use any of these formats to define a middleware:
Middleware will be executed forwards in the same order they are defined. If you define it like the following:
`[$middleware1, $midleware2]`, the execution will look like this:
+
```mermaid
graph LR
StartPush((Start)) --> PushMiddleware1[$middleware1] --> PushMiddleware2[$middleware2] --> Push(Push to a queue)
@@ -238,7 +233,8 @@ graph LR
```
### Push pipeline
-When you push a message, you can use middlewares to modify both message and queue adapter.
+
+When you push a message, you can use middlewares to modify both message and queue adapter.
With message modification you can add extra data, obfuscate data, collect metrics, etc.
With queue adapter modification you can redirect message to another queue, delay message consuming, and so on.
@@ -256,17 +252,17 @@ in the `PushRequest` object. You will get a `AdapterNotConfiguredException`, if
You have three places to define push middlewares:
1. `PushMiddlewareDispatcher`. You can pass it either to the constructor, or to the `withMiddlewares()` method, which
-creates a completely new dispatcher object with only those middlewares, which are passed as arguments.
-If you use [yiisoft/config](yiisoft/config), you can add middleware to the `middlewares-push` key of the
+creates a completely new dispatcher object with only those middlewares, which are passed as arguments.
+If you use [yiisoft/config](yiisoft/config), you can add middleware to the `middlewares-push` key of the
`yiisoft/queue` array in the `params`.
-2. Pass middlewares to either `Queue::withMiddlewares()` or `Queue::withMiddlewaresAdded()` methods. The difference is
-that the former will completely replace an existing middleware stack, while the latter will add passed middlewares to
-the end of the existing stack. These middlewares will be executed after the common ones, passed directly to the
-`PushMiddlewareDispatcher`. It's useful when defining a queue channel. Both methods return a new instance of the `Queue`
+2. Pass middlewares to either `Queue::withMiddlewares()` or `Queue::withMiddlewaresAdded()` methods. The difference is
+that the former will completely replace an existing middleware stack, while the latter will add passed middlewares to
+the end of the existing stack. These middlewares will be executed after the common ones, passed directly to the
+`PushMiddlewareDispatcher`. It's useful when defining a queue channel. Both methods return a new instance of the `Queue`
class.
3. Put middlewares into the `Queue::push()` method like this: `$queue->push($message, ...$middlewares)`. These
-middlewares have the lowest priority and will be executed after those which are in the `PushMiddlewareDispatcher` and
-the ones passed to the `Queue::withMiddlewares()` and `Queue::withMiddlewaresAdded()` and only for the message passed
+middlewares have the lowest priority and will be executed after those which are in the `PushMiddlewareDispatcher` and
+the ones passed to the `Queue::withMiddlewares()` and `Queue::withMiddlewaresAdded()` and only for the message passed
along with them.
### Consume pipeline
@@ -276,6 +272,7 @@ You can set a middleware pipeline for a message when it will be consumed from a
### Error handling pipeline
Often when some job is failing, we want to retry its execution a couple more times or redirect it to another queue channel. This can be done in `yiisoft/queue` with Failure middleware pipeline. They are triggered each time message processing via the Consume middleware pipeline is interrupted with any `Throwable`. The key differences from the previous two pipelines:
+
- You should set up the middleware pipeline separately for each queue channel. That means, the format should be `['channel-name' => [FooMiddleware::class]]` instead of `[FooMiddleware::class]`, like for the other two pipelines. There is also a default key, which will be used for those channels without their own one: `FailureMiddlewareDispatcher::DEFAULT_PIPELINE`.
- The last middleware will throw the exception, which will come with the `FailureHandlingRequest` object. If you don't want the exception to be thrown, your middlewares should `return` a request without calling `$handler->handleFailure()`.
@@ -283,31 +280,20 @@ You can declare error handling middleware pipeline in the `FailureMiddlewareDisp
See [error handling docs](docs/guide/error-handling.md) for details.
-## Extra
+## Documentation
-### Unit testing
+- [Guide](docs/guide/en/README.md)
+- [Internals](docs/internals.md)
-The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
-```shell
-./vendor/bin/phpunit
-```
-
-### Mutation testing
-
-The package tests are checked with [Infection](https://infection.github.io/) mutation framework. To run it:
-
-```shell
-./vendor/bin/infection
-```
-
-### Static analysis
+## License
-The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
+The Yii Queue is free software. It is released under the terms of the BSD License.
+Please see [`LICENSE`](./LICENSE.md) for more information.
-```shell
-./vendor/bin/psalm
-```
+Maintained by [Yii Software](https://www.yiiframework.com/).
### Support the project
@@ -320,10 +306,3 @@ The code is statically analyzed with [Psalm](https://psalm.dev/). To run static
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)
-
-## License
-
-The Yii Queue Extension is free software. It is released under the terms of the BSD License.
-Please see [`LICENSE`](./LICENSE.md) for more information.
-
-Maintained by [Yii Software](https://www.yiiframework.com/).
diff --git a/UPGRADE.md b/UPGRADE.md
index 426b6ef3..c1aa6527 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,6 +1,6 @@
-Upgrading Instructions
-======================
+# Yii Queue Upgrading Instructions
This file contains the upgrade notes. These notes highlight changes that could break your
application when you upgrade the package from one version to another.
+## Changes summary
diff --git a/composer.json b/composer.json
index 69d46812..c59f8ca9 100644
--- a/composer.json
+++ b/composer.json
@@ -17,12 +17,22 @@
"license": "BSD-3-Clause",
"support": {
"issues": "https://github.com/yiisoft/queue/issues?state=open",
+ "source": "https://github.com/yiisoft/queue",
"forum": "https://www.yiiframework.com/forum/",
"wiki": "https://www.yiiframework.com/wiki/",
"irc": "ircs://irc.libera.chat:6697/yii",
- "chat": "https://t.me/yii3en",
- "source": "https://github.com/yiisoft/queue"
+ "chat": "https://t.me/yii3en"
},
+ "funding": [
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/yiisoft"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/yiisoft"
+ }
+ ],
"minimum-stability": "dev",
"prefer-stable": true,
"require": {
diff --git a/docs/guide/README.md b/docs/guide/README.md
deleted file mode 100644
index 6d6f175a..00000000
--- a/docs/guide/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Yii Queue extension
-
-An extension for running tasks asynchronously via queues.
-
-## Guides and concept explanations
-
-* [Usage basics](usage.md)
-* [Migrating from `yii2-queue`](migrating-from-yii2-queue.md)
-* [Errors and retryable jobs](error-handling.md)
-* [Workers](worker.md)
-* [Adapter list](adapter-list.md)
diff --git a/docs/guide/en/README.md b/docs/guide/en/README.md
new file mode 100644
index 00000000..564b8ca9
--- /dev/null
+++ b/docs/guide/en/README.md
@@ -0,0 +1,11 @@
+# Yii Queue
+
+An extension for running tasks asynchronously via queues.
+
+## Guides and concept explanations
+
+- [Usage basics](usage.md)
+- [Migrating from `yii2-queue`](migrating-from-yii2-queue.md)
+- [Errors and retryable jobs](error-handling.md)
+- [Workers](worker.md)
+- [Adapter list](adapter-list.md)
diff --git a/docs/guide/adapter-list.md b/docs/guide/en/adapter-list.md
similarity index 100%
rename from docs/guide/adapter-list.md
rename to docs/guide/en/adapter-list.md
diff --git a/docs/guide/adapter-sync.md b/docs/guide/en/adapter-sync.md
similarity index 100%
rename from docs/guide/adapter-sync.md
rename to docs/guide/en/adapter-sync.md
diff --git a/docs/guide/error-handling.md b/docs/guide/en/error-handling.md
similarity index 100%
rename from docs/guide/error-handling.md
rename to docs/guide/en/error-handling.md
diff --git a/docs/guide/loops.md b/docs/guide/en/loops.md
similarity index 100%
rename from docs/guide/loops.md
rename to docs/guide/en/loops.md
diff --git a/docs/guide/migrating-from-yii2-queue.md b/docs/guide/en/migrating-from-yii2-queue.md
similarity index 100%
rename from docs/guide/migrating-from-yii2-queue.md
rename to docs/guide/en/migrating-from-yii2-queue.md
diff --git a/docs/guide/usage.md b/docs/guide/en/usage.md
similarity index 100%
rename from docs/guide/usage.md
rename to docs/guide/en/usage.md
diff --git a/docs/guide/worker.md b/docs/guide/en/worker.md
similarity index 100%
rename from docs/guide/worker.md
rename to docs/guide/en/worker.md
diff --git a/docs/internals.md b/docs/internals.md
new file mode 100644
index 00000000..087a514a
--- /dev/null
+++ b/docs/internals.md
@@ -0,0 +1,44 @@
+# Internals
+
+## Unit testing
+
+The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
+
+```shell
+./vendor/bin/phpunit
+```
+
+## Mutation testing
+
+The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
+[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
+
+```shell
+./vendor/bin/roave-infection-static-analysis-plugin
+```
+
+## Static analysis
+
+The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
+
+```shell
+./vendor/bin/psalm
+```
+
+## Code style
+
+Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or
+use either newest or any specific version of PHP:
+
+```shell
+./vendor/bin/rector
+```
+
+## Dependencies
+
+This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if
+all dependencies are correctly defined in `composer.json`. To run the checker, execute the following command:
+
+```shell
+./vendor/bin/composer-require-checker
+```