yiisoft · vjik · May 21, 2024 · May 6, 2024 · May 18, 2024 · May 18, 2024
diff --git a/README.md b/README.md
@@ -1,15 +1,11 @@
 <p align="center">
     <a href="https://github.com/yiisoft" target="_blank">
-        <img src="https://avatars0.githubusercontent.com/u/993323" height="100px">
+        <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px" alt="Yii">
     </a>
-    <h1 align="center">Yii Queue Extension</h1>
+    <h1 align="center">Yii Queue</h1>
     <br>
 </p>
 
-An extension for running tasks asynchronously via queues.
-
-Documentation is at [docs/guide/README.md](docs/guide/README.md).
-
 [![Latest Stable Version](https://poser.pugx.org/yiisoft/queue/v/stable.svg)](https://packagist.org/packages/yiisoft/queue)
 [![Total Downloads](https://poser.pugx.org/yiisoft/queue/downloads.svg)](https://packagist.org/packages/yiisoft/queue)
 [![Build status](https://github.com/yiisoft/queue/workflows/build/badge.svg)](https://github.com/yiisoft/queue/actions)
@@ -19,29 +15,26 @@ Documentation is at [docs/guide/README.md](docs/guide/README.md).
 [![static analysis](https://github.com/yiisoft/queue/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/queue/actions?query=workflow%3A%22static+analysis%22)
 [![type-coverage](https://shepherd.dev/github/yiisoft/queue/coverage.svg)](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,38 +272,28 @@ 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()`.
 
 You can declare error handling middleware pipeline in the `FailureMiddlewareDispatcher`, either in the constructor, or in the `withMiddlewares()` method. If you use [yiisoft/config](yiisoft/config), you can add middleware to the `middlewares-fail` key of the `yiisoft/queue` array in the `params`.
 
 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
 [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
 [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
 [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](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
@@ -1,6 +1,3 @@
-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.
+# Yii Queue Upgrading Instructions
 
+## Changes summary
diff --git 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
diff --git a/docs/guide/en/README.md 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 → docs/guide/en/adapter-list.md b/docs/guide/adapter-list.md → docs/guide/en/adapter-list.md
diff --git a/docs/guide/adapter-sync.md → docs/guide/en/adapter-sync.md b/docs/guide/adapter-sync.md → docs/guide/en/adapter-sync.md
diff --git a/docs/guide/error-handling.md → docs/guide/en/error-handling.md b/docs/guide/error-handling.md → docs/guide/en/error-handling.md
diff --git a/docs/guide/loops.md → docs/guide/en/loops.md b/docs/guide/loops.md → docs/guide/en/loops.md
diff --git a/docs/guide/migrating-from-yii2-queue.md → docs/guide/en/migrating-from-yii2-queue.md b/docs/guide/migrating-from-yii2-queue.md → docs/guide/en/migrating-from-yii2-queue.md
diff --git a/docs/guide/usage.md → docs/guide/en/usage.md b/docs/guide/usage.md → docs/guide/en/usage.md
diff --git a/docs/guide/worker.md → docs/guide/en/worker.md b/docs/guide/worker.md → docs/guide/en/worker.md
diff --git a/docs/internals.md 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
+```