From 7f64bc1a360432aaf1f21f6be6a650cf4ed1f465 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Mon, 14 Sep 2020 11:10:55 +0300 Subject: [PATCH 01/12] Update README --- README.md | 42 +++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a2409ca1..7512da90 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,6 @@ An extension for running tasks asynchronously via queues. -It supports queues based on **DB**, **Redis**, **RabbitMQ**, **AMQP**, **Beanstalk** and **Gearman**. - Documentation is at [docs/guide/README.md](docs/guide/README.md). [![Latest Stable Version](https://poser.pugx.org/yiisoft/yii-queue/v/stable.svg)](https://packagist.org/packages/yiisoft/yii-queue) @@ -44,7 +42,7 @@ Each task which is sent to queue should be defined as a separate class. For example, if you need to download and save a file the class may look like the following: ```php -class DownloadJob implements \Yiisoft\Yii\Queue\JobInterface +class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface { public $url; public $file; @@ -55,28 +53,47 @@ class DownloadJob implements \Yiisoft\Yii\Queue\JobInterface $this->file = $file; } - public function execute($queue) + public function getName(): string + { + return 'earlyDefinedQueueHandlerName'; + } + + public function getData() { file_put_contents($this->file, file_get_contents($this->url)); } + + public function getMeta(): array + { + return []; + } } ``` Here's how to send a task into the queue: ```php -Yii::$app->queue->push( +$queue->push( new DownloadJob('http://example.com/image.jpg', '/tmp/image.jpg') ); ``` To push a job into the queue that should run after 5 minutes: ```php -Yii::$app->queue->delay(5 * 60)->push( - new DownloadJob('http://example.com/image.jpg', '/tmp/image.jpg') +$queue->push( + new class('http://example.com/image.jpg', '/tmp/image.jpg') extends DownloadJob + implements \Yiisoft\Yii\Queue\Payload\DelayablePayloadInterface { + + public function getDelay(): int + { + return 5 * 60; + } + } ); ``` +**Important:** Not all drivers(i.e. synchronous driver) support delayed running. + The exact way a task is executed depends on the used driver. Most drivers can be run using console commands, which the component automatically registers in your application. @@ -98,16 +115,19 @@ The component also has the ability to track the status of a job which was pushed ```php // Push a job into the queue and get a message ID. -$id = Yii::$app->queue->push(new SomeJob()); +$id = $queue->push(new SomeJob()); + +//Get status of job +$status = $queue->status($id); // Check whether the job is waiting for execution. -Yii::$app->queue->isWaiting($id); +$status->isWaiting(); // Check whether a worker got the job from the queue and executes it. -Yii::$app->queue->isReserved($id); +$status->isReserved($id); // Check whether a worker has executed the job. -Yii::$app->queue->isDone($id); +$status->isDone($id); ``` For more details see [the guide](docs/guide/README.md). From c5d16a7941de0650f06d655c413f127a6be3e180 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Mon, 14 Sep 2020 14:14:15 +0300 Subject: [PATCH 02/12] Fixes --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7512da90..f4305706 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ $queue->push( ); ``` -**Important:** Not all drivers(i.e. synchronous driver) support delayed running. +**Important:** Not every driver (such as synchronous driver) supports delayed execution. The exact way a task is executed depends on the used driver. Most drivers can be run using console commands, which the component automatically registers in your application. @@ -117,7 +117,7 @@ The component also has the ability to track the status of a job which was pushed // Push a job into the queue and get a message ID. $id = $queue->push(new SomeJob()); -//Get status of job +// Get status of the job $status = $queue->status($id); // Check whether the job is waiting for execution. From 1c88e176d1fbdc53cf13369df54bb19efabe4ee0 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Mon, 14 Sep 2020 17:08:57 +0300 Subject: [PATCH 03/12] Refactor documentation --- docs/guide-ja/README.md | 30 --- docs/guide-ja/debug.md | 22 -- docs/guide-ja/driver-amqp-interop.md | 62 ------ docs/guide-ja/driver-beanstalk.md | 61 ------ docs/guide-ja/driver-db.md | 118 ----------- docs/guide-ja/driver-file.md | 65 ------ docs/guide-ja/driver-gearman.md | 48 ----- docs/guide-ja/driver-redis.md | 76 ------- docs/guide-ja/driver-sqs.md | 64 ------ docs/guide-ja/driver-sync.md | 18 -- docs/guide-ja/gii.md | 28 --- docs/guide-ja/retryable.md | 119 ----------- docs/guide-ja/usage.md | 255 ----------------------- docs/guide-ja/worker.md | 120 ----------- docs/guide-ru/README.md | 30 --- docs/guide-ru/debug.md | 22 -- docs/guide-ru/driver-amqp-interop.md | 71 ------- docs/guide-ru/driver-beanstalk.md | 62 ------ docs/guide-ru/driver-db.md | 120 ----------- docs/guide-ru/driver-file.md | 65 ------ docs/guide-ru/driver-gearman.md | 49 ----- docs/guide-ru/driver-redis.md | 73 ------- docs/guide-ru/driver-sqs.md | 65 ------ docs/guide-ru/driver-sync.md | 18 -- docs/guide-ru/gii.md | 28 --- docs/guide-ru/retryable.md | 122 ----------- docs/guide-ru/usage.md | 257 ------------------------ docs/guide-ru/worker.md | 125 ------------ docs/guide-zh-CN/README.md | 24 --- docs/guide-zh-CN/debug.md | 22 -- docs/guide-zh-CN/driver-amqp-interop.md | 67 ------ docs/guide-zh-CN/driver-beanstalk.md | 58 ------ docs/guide-zh-CN/driver-db.md | 114 ----------- docs/guide-zh-CN/driver-file.md | 62 ------ docs/guide-zh-CN/driver-gearman.md | 48 ----- docs/guide-zh-CN/driver-redis.md | 69 ------- docs/guide-zh-CN/driver-sync.md | 18 -- docs/guide-zh-CN/retryable.md | 98 --------- docs/guide-zh-CN/usage.md | 250 ----------------------- docs/guide-zh-CN/worker.md | 117 ----------- docs/guide/README.md | 16 +- docs/guide/debug.md | 22 -- docs/guide/driver-amqp-interop.md | 62 ------ docs/guide/driver-beanstalk.md | 61 ------ docs/guide/driver-db.md | 118 ----------- docs/guide/driver-file.md | 65 ------ docs/guide/driver-gearman.md | 48 ----- docs/guide/driver-redis.md | 76 ------- docs/guide/driver-sqs.md | 62 ------ docs/guide/gii.md | 28 --- docs/guide/usage.md | 190 ++++++------------ 51 files changed, 63 insertions(+), 3825 deletions(-) delete mode 100644 docs/guide-ja/README.md delete mode 100644 docs/guide-ja/debug.md delete mode 100644 docs/guide-ja/driver-amqp-interop.md delete mode 100644 docs/guide-ja/driver-beanstalk.md delete mode 100644 docs/guide-ja/driver-db.md delete mode 100644 docs/guide-ja/driver-file.md delete mode 100644 docs/guide-ja/driver-gearman.md delete mode 100644 docs/guide-ja/driver-redis.md delete mode 100644 docs/guide-ja/driver-sqs.md delete mode 100644 docs/guide-ja/driver-sync.md delete mode 100644 docs/guide-ja/gii.md delete mode 100644 docs/guide-ja/retryable.md delete mode 100644 docs/guide-ja/usage.md delete mode 100644 docs/guide-ja/worker.md delete mode 100644 docs/guide-ru/README.md delete mode 100644 docs/guide-ru/debug.md delete mode 100644 docs/guide-ru/driver-amqp-interop.md delete mode 100644 docs/guide-ru/driver-beanstalk.md delete mode 100644 docs/guide-ru/driver-db.md delete mode 100644 docs/guide-ru/driver-file.md delete mode 100644 docs/guide-ru/driver-gearman.md delete mode 100644 docs/guide-ru/driver-redis.md delete mode 100644 docs/guide-ru/driver-sqs.md delete mode 100644 docs/guide-ru/driver-sync.md delete mode 100644 docs/guide-ru/gii.md delete mode 100644 docs/guide-ru/retryable.md delete mode 100644 docs/guide-ru/usage.md delete mode 100644 docs/guide-ru/worker.md delete mode 100644 docs/guide-zh-CN/README.md delete mode 100644 docs/guide-zh-CN/debug.md delete mode 100644 docs/guide-zh-CN/driver-amqp-interop.md delete mode 100644 docs/guide-zh-CN/driver-beanstalk.md delete mode 100644 docs/guide-zh-CN/driver-db.md delete mode 100644 docs/guide-zh-CN/driver-file.md delete mode 100644 docs/guide-zh-CN/driver-gearman.md delete mode 100644 docs/guide-zh-CN/driver-redis.md delete mode 100644 docs/guide-zh-CN/driver-sync.md delete mode 100644 docs/guide-zh-CN/retryable.md delete mode 100644 docs/guide-zh-CN/usage.md delete mode 100644 docs/guide-zh-CN/worker.md delete mode 100644 docs/guide/debug.md delete mode 100644 docs/guide/driver-amqp-interop.md delete mode 100644 docs/guide/driver-beanstalk.md delete mode 100644 docs/guide/driver-db.md delete mode 100644 docs/guide/driver-file.md delete mode 100644 docs/guide/driver-gearman.md delete mode 100644 docs/guide/driver-redis.md delete mode 100644 docs/guide/driver-sqs.md delete mode 100644 docs/guide/gii.md diff --git a/docs/guide-ja/README.md b/docs/guide-ja/README.md deleted file mode 100644 index c08f6fbe..00000000 --- a/docs/guide-ja/README.md +++ /dev/null @@ -1,30 +0,0 @@ -Yii2 キュー・エクステンション -============================= - -キューによってタスクを非同期に走らせるためのエクステンション。 - -導入 ----- - -* [基本的な使用方法](usage.md) -* [エラーと再試行可能ジョブ](retryable.md) -* [ワーカを開始する](worker.md) - -キュー・ドライバ ----------------- - -* [同期](driver-sync.md) -* [ファイル](driver-file.md) -* [データベース](driver-db.md) -* [Redis](driver-redis.md) -* [RabbitMQ](driver-amqp.md) -* [AMQP Interop](driver-amqp-interop.md) -* [Beanstalk](driver-beanstalk.md) -* [Gearman](driver-gearman.md) -* [AWS SQS](driver-sqs.md) - -開発ツール ----------- - -* [デバッグ](debug.md) -* [Gii コード・ジェネレータ](gii.md) diff --git a/docs/guide-ja/debug.md b/docs/guide-ja/debug.md deleted file mode 100644 index 2b92849d..00000000 --- a/docs/guide-ja/debug.md +++ /dev/null @@ -1,22 +0,0 @@ -デバッグ -======== - -開発中は、Yii2 デバッグ・モジュールのためのパネルを追加したいと思うことも有るでしょう。 -このパネルは、キューにあるタスクのカウンタとリストを表示します。 - -このパネルが表示されるためには、`yiisoft/yii2-debug` モジュールがアプリケーションにインストールされていなければなりません。 - -以下のようにアプリケーションを構成して下さい。 - -```php -return [ - 'modules' => [ - 'debug' => [ - 'class' => \yii\debug\Module::class, - 'panels' => [ - 'queue' => \Yiisoft\Yii\Queue\Debug\Panel::class, - ], - ], - ], -]; -``` diff --git a/docs/guide-ja/driver-amqp-interop.md b/docs/guide-ja/driver-amqp-interop.md deleted file mode 100644 index 88f46df9..00000000 --- a/docs/guide-ja/driver-amqp-interop.md +++ /dev/null @@ -1,62 +0,0 @@ -AMQP Interop -============ - -このドライバは RabbitMQ のキューによって動作します。 - -[amqp interop](https://github.com/queue-interop/queue-interop#amqp-interop) 互換のトランスポート、 -例えば `enqueue/amqp-lib` パッケージを必要とします。 - -利点: - -* amqp interop 互換のトランスポートであれば、何でも動作します。例えば、 - - * [PHP amqp extension](https://github.com/pdezwart/php-amqp) に基づく [enqueue/amqp-ext](https://github.com/php-enqueue/amqp-ext) - * [php-amqplib/php-amqplib](https://github.com/php-amqplib/php-amqplib) に基づく [enqueue/amqp-lib](https://github.com/php-enqueue/amqp-lib) - * [bunny](https://github.com/jakubkulhan/bunny) に基づく [enqueue/amqp-bunny](https://github.com/php-enqueue/amqp-bunny) - -* 優先度をサポート -* 遅延をサポート -* TTR をサポート -* 試行回数をサポート -* 新しいオプション: vhost, connection_timeout, qos_prefetch_count 等々 -* Secure (SSL) AMQP 接続をサポート -* DSN を設定できる: 例えば、amqp:, amqps: または amqp://user:pass@localhost:1000/vhost - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Interop\Queue::class, - 'port' => 5672, - 'user' => 'guest', - 'password' => 'guest', - 'queueName' => 'queue', - 'driver' => Yiisoft\Yii\Queue\Drivers\Interop\Queue::ENQUEUE_AMQP_LIB, - - // または - 'dsn' => 'amqp://guest:guest@localhost:5672/%2F', - - // または、上記と同じ - 'dsn' => 'amqp:', - ], - ], -]; -``` - -コンソール ----------- - -キューに入れられたジョブを実行するためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen -``` - -`listen` コマンドが無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 diff --git a/docs/guide-ja/driver-beanstalk.md b/docs/guide-ja/driver-beanstalk.md deleted file mode 100644 index 1258cbf7..00000000 --- a/docs/guide-ja/driver-beanstalk.md +++ /dev/null @@ -1,61 +0,0 @@ -Beanstalk ドライバ -================== - -このドライバは Beanstalk のキューによって動作します。 - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\beanstalk\Queue::class, - 'host' => 'localhost', - 'port' => 11300, - 'tube' => 'queue', - ], - ], -]; -``` - -コンソール ----------- - -キューに入れられたジョブの実行と管理のためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドは無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはキューを調べる間のスリープの秒数を指定するものです。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 - -```sh -yii queue/info -``` - -`info` コマンドはキューの状態について情報を表示します。 - -```sh -yii queue/remove [id] -``` - -`remove` コマンドはキューからジョブを削除します。 diff --git a/docs/guide-ja/driver-db.md b/docs/guide-ja/driver-db.md deleted file mode 100644 index 0281ece2..00000000 --- a/docs/guide-ja/driver-db.md +++ /dev/null @@ -1,118 +0,0 @@ -データベース・ドライバ -====================== - -データベース・ドライバはキューのデータを保存するのにデータベースを使用します。 - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'db' => [ - 'class' => \Yiisoft\Db\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'db' => 'db', // DB 接続コンポーネントまたはその構成情報 - 'tableName' => '{{%queue}}', // テーブル名 - 'channel' => 'default', // キュー・チャンネル・キー - 'mutex' => \Yiisoft\Mutex\MysqlMutex::class, // クエリ同期のための mutex - ], - ], -]; -``` - -データベースにテーブルを追加する必要があります。MySQL のためのスキーマ例: - -```SQL -CREATE TABLE `queue` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `channel` varchar(255) NOT NULL, - `job` blob NOT NULL, - `pushed_at` int(11) NOT NULL, - `ttr` int(11) NOT NULL, - `delay` int(11) NOT NULL DEFAULT 0, - `priority` int(11) unsigned NOT NULL DEFAULT 1024, - `reserved_at` int(11) DEFAULT NULL, - `attempt` int(11) DEFAULT NULL, - `done_at` int(11) DEFAULT NULL, - PRIMARY KEY (`id`), - KEY `channel` (`channel`), - KEY `reserved_at` (`reserved_at`), - KEY `priority` (`priority`) -) ENGINE=InnoDB -``` - -マイグレーションが [src/drivers/db/migrations](../../src/drivers/db/migrations) から取得できます。 - -アプリケーションにマイグレーションを追加するためには、コンソールの構成ファイルを編集して、 -[名前空間化されたマイグレーション](http://www.yiiframework.com/doc-2.0/guide-db-migrations.html#namespaced-migrations) を構成して下さい。 - -```php -'controllerMap' => [ - // ... - 'migrate' => [ - 'class' => 'Yiisoft\Yii\Console\Controllers\MigrateController', - 'migrationPath' => null, - 'migrationNamespaces' => [ - // ... - 'Yiisoft\Yii\Queue\Drivers\Db\migrations', - ], - ], -], -``` - -そして、`migrate/up` コマンドを発行します。 - -```sh -yii migrate/up -``` - -コンソール ----------- - -キューに入れられたジョブの実行と管理のためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドは無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはキューを調べる間のスリープの秒数を指定するものです。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 - -```sh -yii queue/info -``` - -`info` コマンドはキューの状態について情報を表示します。 - -```sh -yii queue/clear -``` - -`clear` コマンドはキューをクリアします。 - -```sh -yii queue/remove [id] -``` - -`remove` コマンドはキューからジョブを削除します。 diff --git a/docs/guide-ja/driver-file.md b/docs/guide-ja/driver-file.md deleted file mode 100644 index a6e609b6..00000000 --- a/docs/guide-ja/driver-file.md +++ /dev/null @@ -1,65 +0,0 @@ -ファイル・ドライバ -================== - -ファイル・ドライバは、キューのデータを保存するのにファイルを使用します。 - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\file\Queue::class, - 'path' => '@runtime/queue', - ], - ], -]; -``` - -コンソール ----------- - -キューに入れられたジョブの実行と管理のためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドは無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはキューを調べる間のスリープの秒数を指定するものです。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 - -```sh -yii queue/info -``` - -`info` コマンドはキューの状態について情報を表示します。 - -```sh -yii queue/clear -``` - -`clear` コマンドはキューをクリアします。 - -```sh -yii queue/remove [id] -``` - -`remove` コマンドはキューからジョブを削除します。 diff --git a/docs/guide-ja/driver-gearman.md b/docs/guide-ja/driver-gearman.md deleted file mode 100644 index 4bc6f3f3..00000000 --- a/docs/guide-ja/driver-gearman.md +++ /dev/null @@ -1,48 +0,0 @@ -Gearman ドライバ -================ - -このドライバは Gearman のキューによって動作します。 - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\gearman\Queue::class, - 'host' => 'localhost', - 'port' => 4730, - 'channel' => 'my_queue', - ], - ], -]; -``` - -コンソール ----------- - -キューに入れられたジョブの実行と管理のためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドは無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはキューを調べる間のスリープの秒数を指定するものです。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 diff --git a/docs/guide-ja/driver-redis.md b/docs/guide-ja/driver-redis.md deleted file mode 100644 index 31969cb0..00000000 --- a/docs/guide-ja/driver-redis.md +++ /dev/null @@ -1,76 +0,0 @@ -Redis ドライバ -============== - -このドライバはキューのデータを保存するのに Redis を使います。 - -使用するためには `yiisoft/yii2-redis` エクステンションをアプリケーションに追加しなければなりません。 - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'redis' => [ - 'class' => \yii\redis\Connection::class, - // ... - - // 接続がタイムアウトした後の接続再試行回数 - // yiisoft/yii2-redis が 2.0.7 以降の場合はこれが必要 - 'retries' => 1, - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'redis' => 'redis', // Redis 接続コンポーネントまたはその構成情報 - 'channel' => 'queue', // キュー・チャンネル・キー - ], - ], -]; -``` - -コンソール ----------- - -キューに入れられたジョブの実行と管理のためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドは無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはキューを調べる間のスリープの秒数を指定するものです。 -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 - -```sh -yii queue/info -``` - -`info` コマンドはキューの状態について情報を表示します。 - -```sh -yii queue/clear -``` - -`clear` コマンドはキューをクリアします。 - -```sh -yii queue/remove [id] -``` - -`remove` コマンドはキューからジョブを削除します。 diff --git a/docs/guide-ja/driver-sqs.md b/docs/guide-ja/driver-sqs.md deleted file mode 100644 index 505850e6..00000000 --- a/docs/guide-ja/driver-sqs.md +++ /dev/null @@ -1,64 +0,0 @@ -AWS SQS ドライバ -================ - -このドライバはキューのデータを保存するのに AWS SQS を使います。 - -これを使用するためには、あなたのアプリケーションに `aws/aws-sdk-php` エクステンションを追加する必要があります。 - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue', // コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\sqs\Queue::class, - 'url' => '', - 'key' => '', - 'secret' => '', - 'region' => '', - ], - ], -]; -``` - -コンソール ----------- - -タスクを実行するためにコンソール・コマンドが使用されます。 - -```sh -yii queue/listen [timeout] -``` - -`listen` コマンドが無限にキューを調べ続けるデーモンを起動します。キューに新しいタスクがあると、即座に取得され、実行されます。 -`timeout` パラメータはジョブを待つ秒数を指定するものです。 -デーモンは、クライアントとキューの間の接続を保持する SQS の "Long Polling" 機能を使います。 - -**重要** SQS ドライバの `timeout` パラメータは 0 から 20 秒の範囲内になければなりません。 - -このコマンドを [supervisor](worker.md#supervisor) または [systemd](worker.md#systemd) によって適切にデーモン化するのが、 -最も効率的な方法です。 - -```sh -yii queue/run -``` - -`run` コマンドは、キューが空になるまでループして、タスクを取得し、実行します。 -[cron](worker.md#cron) に向いた方法です。 - -`run` および `listen` のコマンドは下記のオプションを持っています。 - -- `--verbose`, `-v`: 実行の状態をコンソールに表示します。 -- `--isolate`: ジョブ実行の饒舌モード。有効な場合、各ジョブの実行結果が表示されます。 -- `--color`: 饒舌モードでハイライトを有効にします。 - -```sh -yii queue/clear -``` - -`clear` コマンドはキューをクリアします。 - - diff --git a/docs/guide-ja/driver-sync.md b/docs/guide-ja/driver-sync.md deleted file mode 100644 index e3ade9c9..00000000 --- a/docs/guide-ja/driver-sync.md +++ /dev/null @@ -1,18 +0,0 @@ -同期ドライバ -============ - -`handle` プロパティが立っている場合に、同じプロセス内で同期的にタスクを実行します。 -アプリケーションの開発とデバッグに使用することが出来ます。 - -構成例: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Sync\Queue::class, - 'handle' => false, // タスクを即時に実行するかどうか - ], - ], -]; -``` diff --git a/docs/guide-ja/gii.md b/docs/guide-ja/gii.md deleted file mode 100644 index 13d67a28..00000000 --- a/docs/guide-ja/gii.md +++ /dev/null @@ -1,28 +0,0 @@ -Gii コード・ジェネレータ -======================== - -ジョブのテンプレートを生成するために Gii コード・ジェネレータを使用することが出来ます。 - -構成 ----- - -Gii ジョブ・ジェネレータを使うためには、以下のように構成しなければなりません。 - -```php -if (!YII_ENV_TEST) { - $config['bootstrap'][] = 'gii'; - $config['modules']['gii'] = [ - 'class' => 'Yiisoft\Yii\Gii\Module', - 'generators' => [ - 'job' => [ - 'class' => \Yiisoft\Yii\Queue\Gii\Generator::class, - ], - ], - ]; -} - -``` - -このようにすると、Gii のメニューにジョブ・ジェネレータが表示されるようになります。 - -![default](https://user-images.githubusercontent.com/1656851/29426628-e9a3e5ae-838f-11e7-859f-6f3cb8649f02.png) diff --git a/docs/guide-ja/retryable.md b/docs/guide-ja/retryable.md deleted file mode 100644 index ba2ada5c..00000000 --- a/docs/guide-ja/retryable.md +++ /dev/null @@ -1,119 +0,0 @@ -エラーと再試行可能ジョブ -======================== - -ジョブの実行は失敗する可能性があります。下手に書かれたコードによる内部的なエラーによって失敗する場合は、 -まずもってコードを修正すべきです。 -しかし、また、サービスやリソースが利用できないなど、外部的な問題によって -ジョブの実行が失敗する場合もあります。その場合は例外やタイムアウトになり得ます。 - -後者の場合においては、いくらか時間をおいて再試行できる方が良いでしょう。そうするための方法がいくつかあります。 - -> **Note:** 下記で説明する `ttr` 機能を使用するためには -> [PHP プロセス制御 (pcntl) 拡張](http://php.net/manual/ja/book.pcntl.php) がインストールされている必要があり、 -> ワーカのコマンドが `--isolate` オプション (デフォルトで有効になっています) を使用する必要があります。 - -再試行のオプション ------------------- - -第一の方法はキュー・コンポーネントのオプションを使うものです。 - -```php -'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'ttr' => 5 * 60, // ジョブ実行の最大時間 - 'attempts' => 3, // 試行の最大回数 - ], -], -``` - -`ttr` (Time to reserve) オプションは、一つのジョブが成功裏に完了されるべき所要時間の最大の秒数を設定します。 -ジョブが失敗するのには、次の二つの場合があります。 - - 1. `ttr` が経過する前にジョブが例外を投げる - 2. ジョブが完了するのに `ttr` よりも長く時間がかかる (タイムアウト)。 - そのためジョブの実行がワーカによって停止される。 - -どちらの場合も、ジョブは後で再試行するためにキューに戻されます。 -ただし、注意してほしいのは、第一の場合において、ジョブが開始直後に停止したときでも、 -`ttr` は同じように"消費"される、ということです。 -つまり、`ttr` の残りの秒数が経過しなければジョブはキューに戻されません。 - -`attempts` オプションが試行の最大回数を設定します。 -この数に達してもまだ完了しない場合、ジョブは終了したものとしてキューから削除されます。 - -これらのオプションはキューの中の全てのジョブに適用されます。この振る舞いを特定のジョブについて変更したい場合は、 -次の方法を参照して下さい。 - -RetryableJobInterface ---------------------- - -再試行のロジックをもっと詳細に制御するために、ジョブは `RetryableJobInterface` を実装することが出来ます。 -例えば、 - -```php -class SomeJob extends BaseObject implements RetryableJobInterface -{ - public function execute($queue) - { - //... - } - - public function getTtr() - { - return 15 * 60; - } - - public function canRetry($attempt, $error) - { - return ($attempt < 5) && ($error instanceof TemporaryException); - } -} -``` - -`getTtr()` および `canRetry()` のメソッドは、上述したコンポーネントのオプションより高い優先度を持ちます。 - -イベント・ハンドラ ------------------- - -TTR と失敗したジョブの再試行回数を制御する第三の方法は、`Queue::EVENT_BEFORE_PUSH` と -`Queue::EVENT_AFTER_ERROR` のイベントを利用するものです。 - -TTR は `Queue::EVENT_BEFORE_PUSH` イベントによって設定することが出来ます。 - -```php -Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) { - if ($event->job instanceof SomeJob) { - $event->ttr = 300; - } -}); -``` - -そして `Queue::EVENT_AFTER_ERROR` イベントを使って、もう一度試行するかどうかを決定することが出来ます。 - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) { - if ($event->job instanceof SomeJob) { - $event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException); - } -}); -``` - -イベント・ハンドラは `RetryableJobInterface` のメソッドの後で実行され、従って、 -最も高い優先度を持ちます。 - -制約 ----- - -ジョブの再試行のフル・サポートが実装されているのは、[Beanstalk]、[データベース]、[ファイル]、[AMQP Interop] および [Redis] のドライバです。 -[同期] ドライバは失敗したジョブを再試行しません。 [Gearman] ドライバは、再試行可能ジョブをサポートしていません。 -[RabbitMQ] は基本的な再試行のみをサポートしており、試行回数は指定することが出来ません。 - -[Beanstalk]: driver-beanstalk.md -[データベース]: driver-db.md -[ファイル]: driver-file.md -[Redis]: driver-redis.md -[同期]: driver-sync.md -[Gearman]: driver-gearman.md -[RabbitMQ]: driver-amqp.md -[AMQP Interop]: driver-amqp-interop.md diff --git a/docs/guide-ja/usage.md b/docs/guide-ja/usage.md deleted file mode 100644 index f439a50e..00000000 --- a/docs/guide-ja/usage.md +++ /dev/null @@ -1,255 +0,0 @@ -基本的な使用方法 -================ - - -構成 ----- - -このエクステンションを使うためには、以下のように構成しなければなりません。 - -```php -return [ - 'bootstrap' => [ - 'queue', // queue コンポーネントが自身のコンソール・コマンドを登録します - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class, - // 他のドライバ・オプション - ], - ], -]; -``` - -利用可能なドライバとそのドキュメントは [目次](README.md) に記載されています。 - - -使用方法 --------- - -キューに送られるタスクはそれぞれ独立したクラスとして定義されなければなりません。 -例えば、ファイルをダウンロードして保存すう必要がある場合、そのクラスは以下のようなものになります。 - -```php -class DownloadJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $url; - public $file; - - public function execute($queue) - { - file_put_contents($this->file, file_get_contents($this->url)); - } -} -``` - -以下のようにして、キューにタスクを送ります。 - -```php -Yii::$app->queue->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` -5 分後に走るべきジョブをキューにプッシュするには、 - -```php -Yii::$app->queue->delay(5 * 60)->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` - -**重要:** 全てのドライバが遅延実行をサポートしている訳ではありません。 - - -キューの処理 ------------- - -タスクがどのように実行されるかは、正確には、使用されるドライバに依存します。 -ほとんどのドライバでは、コンポーネントがアプリケーションに登録したコンソール・コマンドを使って実行されます。 -詳細は、対応するドライバのドキュメントを参照して下さい。 - - -ジョブの状態 ------------- - -queue コンポーネントは、キューにプッシュされたジョブの状態を追跡することが出来ます。 - -```php -// ジョブをキューにプッシュして、メッセージ ID を取得する -$id = Yii::$app->queue->push(new SomeJob()); - -// ジョブが実行待ちであるかチェックする -Yii::$app->queue->isWaiting($id); - -// ワーカがキューからジョブを受け取って実行しているかチェックする -Yii::$app->queue->isReserved($id); - -// ワーカがジョブを完了したかチェックする -Yii::$app->queue->isDone($id); -``` - -**重要:** RabbitMQ ドライバはジョブの状態追跡をサポートしていません。 - - -サード・パーティのワーカにメッセージを送る ------------------------------------------- - -キューにはどのようなデータでも渡すことが出来ます。 - -```php -Yii::$app->queue->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - -このことは、キューが特別なサード・パーティのワーカを使って処理される場合に有用となります。 - -ワーカが PHP で実装されているのではない場合、データをシリアライズする方法を変更しなければなりません。 -例えば、JSON にシリアライズする場合は、 - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -イベントを処理する ------------------- - -キューは以下のイベントをトリガします。 - -| イベント名 | イベント・クラス | トリガされるタイミング | -|------------------------------|-------------|-----------------------------------------------------------| -| Queue::EVENT_BEFORE_PUSH | PushEvent | `Queue::push()` メソッドを使ってジョブをキューに追加する前 | -| Queue::EVENT_AFTER_PUSH | PushEvent | `Queue::push()` メソッドを使ってジョブをキューに追加した後 | -| Queue::EVENT_BEFORE_EXEC | ExecEvent | ジョブを実行する前 | -| Queue::EVENT_AFTER_EXEC | ExecEvent | ジョブが完了した後 | -| Queue::EVENT_AFTER_ERROR | ExecEvent | ジョブ実行中にキャッチされない例外が発生したとき | -| cli\Queue:EVENT_WORKER_START | WorkerEvent | ワーカが開始されたとき | -| cli\Queue:EVENT_WORKER_LOOP | WorkerEvent | キューに対するリクエストを繰り返すたびに | -| cli\Queue:EVENT_WORKER_STOP | WorkerEvent | ワーカが停止されたとき | - -これらのイベントの全てに対してあなた独自のハンドラをアタッチすることが簡単にできます。 -例えば、ジョブが特殊な例外で失敗した場合に、時間をおいて再実行させてみましょう。 - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function ($event) { - if ($event->error instanceof TemporaryUnprocessableJobException) { - $queue = $event->sender; - $queue->delay(7200)->push($event->job); - } -}); -``` - -イベントのロギング ------------------- - -queue コンポーネントは [Yii の内蔵ロガー](http://www.yiiframework.com/doc-2.0/guide-runtime-logging.html) -を使ってキューのイベントを記録する `LogBehavior` を提供しています。 - -これを有効にするためには、queue コンポーネントを以下のように構成するだけです。 - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class - ], - ], -]; -``` - - -複数のキュー ------------- - -構成例: - -```php -return [ - 'bootstrap' => [ - 'queue1', // 第一のコンポーネントがそれ自身のコンソール・コマンドを登録 - 'queue2', // 第二のコンポーネントがそれ自身のコンソール・コマンドを登録 - ], - 'components' => [ - 'queue1' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - ], - 'queue2' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -使用例: - -```php -// 標準のワーカで処理されるジョブをキューに送る -Yii::$app->queue1->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); - -// サード・パーティのワーカで処理されるタスクを別のキューに送る -Yii::$app->queue2->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - - -制限事項 --------- - -キューを使用する場合、キューに置かれたタスクは独立したプロセスによって取得される、ということを覚えておくことが重要です。 -タスクを実行するときに外部的な依存は避けなければなりません。 -なぜなら、ワーカがジョブを実行する環境においてその依存を利用できるとは限らないからです。 - -タスクを処理するために必要なデータは、ジョブ・オブジェクトのプロパティに設定して、ジョブと一緒にキューに送らなければなりません。 - -`ActiveRecord` を扱う必要がある場合は、オブジェクトそのものではなく、ID を送ります。 -そして、処理するときに DB から読み出します。 - -例えば、 - -```php -Yii::$app->queue->push(new SomeJob([ - 'userId' => Yii::$app->user->id, - 'bookId' => $book->id, - 'someUrl' => Url::to(['controller/action']), -])); -``` - -タスク・クラス: - -```php -class SomeJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $userId; - public $bookId; - public $someUrl; - - public function execute($queue) - { - $user = User::findOne($this->userId); - $book = Book::findOne($this->bookId); - //... - } -} -``` diff --git a/docs/guide-ja/worker.md b/docs/guide-ja/worker.md deleted file mode 100644 index b587d49f..00000000 --- a/docs/guide-ja/worker.md +++ /dev/null @@ -1,120 +0,0 @@ -ワーカを開始する -================ - -Supervisor ----------- - -[Supervisor](http://supervisord.org) は Linux 用のプロセス・モニターで、コンソール・プロセスを自動的に開始できます。 -Ubuntu では、下記のコマンドによってインストールすることが出来ます。 - -```sh -sudo apt-get install supervisor -``` - -Supervisor の構成ファイルは、通常、`/etc/supervisor/conf.d` にあります。 -好きな数だけの構成ファイルをそこに作成することが出来ます。 - -一例を挙げましょう。 - -```conf -[program:yii-queue-worker] -process_name=%(program_name)s_%(process_num)02d -command=/usr/bin/php /var/www/my_project/yii queue/listen --verbose=1 --color=0 -autostart=true -autorestart=true -user=www-data -numprocs=4 -redirect_stderr=true -stdout_logfile=/var/www/my_project/log/yii-queue-worker.log -``` - -この場合、Supervisor は 4 個の `queue/listen` ワーカを開始します。 -ワーカの出力は指定されたログ・ファイルに書かれます。 - -Supervisor の構成と使用方法については、その [ドキュメント](http://supervisord.org) を参照して下さい。 - -`queue/listen` で開始されるワーカ・デーモンがサポートされているのは、[ファイル]、[データベース]、[Redis]、 -[RabbitMQ]、[AMQP Interop]、[Beanstalk] および [Gearman] のドライバだけであることに留意して下さい。追加のオプションについては、ドライバのガイドを参照して下さい。 - -[ファイル]: driver-file.md -[データベース]: driver-db.md -[Redis]: driver-redis.md -[AMQP Interop]: driver-amqp-interop.md -[RabbitMQ]: driver-amqp.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md - -Systemd -------- - -Systemd は、ユーザ空間をブートストラップするために Linux で使用されるもう一つの初期化システムです。 -Systemd を使ってワーカの起動を構成するためには、`/etc/systemd/system` ディレクトリに下記の内容を持った -`yii-queue@.service` という名前の構成ファイルを作成します。 - -```conf -[Unit] -Description=Yii Queue Worker %I -After=network.target -# 次の2行はキューのバックエンドが mysql である場合にのみ当てはまります -# あなたのバックエンドを支持するサービスで置き換えて下さい -After=mysql.service -Requires=mysql.service - -[Service] -User=www-data -Group=www-data -ExecStart=/usr/bin/php /var/www/my_project/yii queue/listen --verbose -Restart=on-failure - -[Install] -WantedBy=multi-user.target -``` - -構成を再読込するためには、systemd をリロードする必要があります。 - -```sh -systemctl daemon-reload -``` - -ワーカを制御する一連のコマンド: - -```sh -# 2つのワーカを開始する -systemctl start yii-queue@1 yii-queue@2 - -# 走っているワーカの状態を取得する -systemctl status "yii-queue@*" - -# 特定のワーカを停止する -systemctl stop yii-queue@2 - -# 走っている全てのワーカを停止する -systemctl stop "yii-queue@*" - -# 2つのワーカをシステムのブート時に開始する -systemctl enable yii-queue@1 yii-queue@2 -``` - -Systemd の全ての機能を学ぶためには、その [ドキュメント](https://freedesktop.org/wiki/Software/systemd/#manualsanddocumentationforusersandadministrators) を参照して下さい。 - -Cron ----- - -Cron を使ってワーカを開始することも出来ます。その場合は `queue/run` コマンドを使う必要があります。 - -構成例: - -```sh -* * * * * /usr/bin/php /var/www/my_project/yii queue/run -``` - -上記の場合、cron はコマンドを1分ごとに実行します。 - -`queue/run` コマンドは、[ファイル], [データベース]、[Redis]、[Beanstalk]、[Gearman] のドライバでサポートされています。 -追加のオプションについては、ドライバのガイドを参照して下さい。 - -[ファイル]: driver-file.md -[データベース]: driver-db.md -[Redis]: driver-redis.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md diff --git a/docs/guide-ru/README.md b/docs/guide-ru/README.md deleted file mode 100644 index 30bd03b2..00000000 --- a/docs/guide-ru/README.md +++ /dev/null @@ -1,30 +0,0 @@ -Расширение Queue для Yii2 -========================= - -Расширение для асинхронного выполнения задач через механизм очередей. - -Введение --------- - -* [Основы использования](usage.md) -* [Ошибки и повторное выполнение](retryable.md) -* [Управление запуском воркеров](worker.md) - -Драйверы очередей ------------------ - -* [Синхронный драйвер](driver-sync.md) -* [Файловый драйвер](driver-file.md) -* [Db драйвер](driver-db.md) -* [Redis драйвер](driver-redis.md) -* [RabbitMQ драйвер](driver-amqp.md) -* [AMQP Interop драйвер](driver-amqp-interop.md) -* [Beanstalk драйвер](driver-beanstalk.md) -* [Gearman драйвер](driver-gearman.md) -* [AWS SQS драйвер](driver-sqs.md) - -Инструменты разработчика ------------------------- - -* [Отладка](debug.md) -* [Генератор кода Gii](gii.md) diff --git a/docs/guide-ru/debug.md b/docs/guide-ru/debug.md deleted file mode 100644 index 0f0ef025..00000000 --- a/docs/guide-ru/debug.md +++ /dev/null @@ -1,22 +0,0 @@ -Отладка -======= - -Для удобств разработки в отладочный модуль Yii2 можно добавить панель, которая будет выводить список -поставленных в очередь заданий, их количество и состояние. - -Отладочное расширение `yiisoft/yii2-debug` должно быть установлено в Вашем приложении. - -Настройка приложения: - -```php -return [ - 'modules' => [ - 'debug' => [ - 'class' => \yii\debug\Module::class, - 'panels' => [ - 'queue' => \Yiisoft\Yii\Queue\Debug\Panel::class, - ], - ], - ], -]; -``` diff --git a/docs/guide-ru/driver-amqp-interop.md b/docs/guide-ru/driver-amqp-interop.md deleted file mode 100644 index 2a01a487..00000000 --- a/docs/guide-ru/driver-amqp-interop.md +++ /dev/null @@ -1,71 +0,0 @@ -AMQP Interop драйвер -==================== - -Драйвер работает с очередью RabbitMQ. - -Чтобы он работал в проект нужно добавить [amqp interop] транспорт, например пакет [enqueue/amqp-lib]. - -Возможности: - -* Транспорты совместимые с [amqp interop]: - * [enqueue/amqp-ext] на основе [PHP amqp extension] - * [enqueue/amqp-lib] на основе [php-amqplib/php-amqplib] - * [enqueue/amqp-bunny] на основе [bunny] -* Приоритеты заданий -* Отложенное выполнение -* Поддерживается TTR -* Повторное выполнение после неудачных попыток -* Опции: `vhost`, `connection_timeout`, `qos_prefetch_count` и т.д. -* Защищенное подключение к брокеру (SSL) -* DSN: `amqp:`, `amqps:` или `amqp://user:pass@localhost:1000/vhost` - -[amqp interop]: https://github.com/queue-interop/queue-interop#amqp-interop -[enqueue/amqp-ext]: https://github.com/php-enqueue/amqp-ext -[PHP amqp extension]: https://github.com/pdezwart/php-amqp -[enqueue/amqp-lib]: https://github.com/php-enqueue/amqp-lib -[php-amqplib/php-amqplib]: https://github.com/php-amqplib/php-amqplib -[enqueue/amqp-bunny]: https://github.com/php-enqueue/amqp-bunny -[bunny]: https://github.com/jakubkulhan/bunny - -Пример конфига: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Interop\Queue::class, - 'port' => 5672, - 'user' => 'guest', - 'password' => 'guest', - 'queueName' => 'queue', - 'driver' => Yiisoft\Yii\Queue\Drivers\Interop\Queue::ENQUEUE_AMQP_LIB, - // или - 'dsn' => 'amqp://guest:guest@localhost:5672/%2F', - // или - 'dsn' => 'amqp:', - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. Способ наиболее эфективен -если запускать команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -Для команды `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. diff --git a/docs/guide-ru/driver-beanstalk.md b/docs/guide-ru/driver-beanstalk.md deleted file mode 100644 index 8be8ceb2..00000000 --- a/docs/guide-ru/driver-beanstalk.md +++ /dev/null @@ -1,62 +0,0 @@ -Beanstalk драйвер -================= - -Драйвер работает с очередью на базе Beanstalk. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\beanstalk\Queue::class, - 'host' => 'localhost', - 'port' => 11300, - 'tube' => 'queue', - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen [timeout] -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. `timeout` - время -ожидания задания из очереди перед следующей итерацией. Способ наиболее эфективен если запускать -команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через -[cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. - -```sh -yii queue/info -``` - -Команда `info` выводит информацию о состоянии очереди. - -```sh -yii queue/remove [id] -``` - -Команда `remove` удаляет задание из очереди. diff --git a/docs/guide-ru/driver-db.md b/docs/guide-ru/driver-db.md deleted file mode 100644 index ded49e73..00000000 --- a/docs/guide-ru/driver-db.md +++ /dev/null @@ -1,120 +0,0 @@ -DB драйвер -========== - -DB дравер для хранения очереди заданий использует базу данных. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'db' => [ - 'class' => \Yiisoft\Db\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'db' => 'db', // Компонент подключения к БД или его конфиг - 'tableName' => '{{%queue}}', // Имя таблицы - 'channel' => 'default', // Выбранный для очереди канал - 'mutex' => \Yiisoft\Mutex\MysqlMutex::class, // Мьютекс для синхронизации запросов - ], - ], -]; -``` - -В базу данных нужно добавить таблицу. Схема, на примере MySQL: - -```SQL -CREATE TABLE `queue` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `channel` varchar(255) NOT NULL, - `job` blob NOT NULL, - `pushed_at` int(11) NOT NULL, - `ttr` int(11) NOT NULL, - `delay` int(11) NOT NULL DEFAULT 0, - `priority` int(11) unsigned NOT NULL DEFAULT 1024, - `reserved_at` int(11) DEFAULT NULL, - `attempt` int(11) DEFAULT NULL, - `done_at` int(11) DEFAULT NULL, - PRIMARY KEY (`id`), - KEY `channel` (`channel`), - KEY `reserved_at` (`reserved_at`), - KEY `priority` (`priority`) -) ENGINE=InnoDB -``` - -Миграции смотрите в [src/drivers/db/migrations](../../src/drivers/db/migrations). - -Расширение предлагает использовать -[миграции с неймспейсами](http://www.yiiframework.com/doc-2.0/guide-db-migrations.html#namespaced-migrations). -Чтобы добавить их в ваше приложение отредактируйте консольный конфиг: - -```php -'controllerMap' => [ - // ... - 'migrate' => [ - 'class' => 'Yiisoft\Yii\Console\Controllers\MigrateController', - 'migrationPath' => null, - 'migrationNamespaces' => [ - // ... - 'Yiisoft\Yii\Queue\Drivers\Db\migrations', - ], - ], -], -``` - -Затем запустите команду: - -```sh -yii migrate/up -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen [timeout] -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. `timeout` - время -ожидания в секундах перед следующим опросом очереди. Способ наиболее эфективен если запускать -команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через -[cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. - -```sh -yii queue/info -``` - -Команда `info` выводит инофрмацию о состоянии очереди. - -```sh -yii queue/clear -``` - -Команда `clear` делает полную очистку очереди. - -```sh -yii queue/remove [id] -``` - -Команда `remove` удаляет задание из очереди. diff --git a/docs/guide-ru/driver-file.md b/docs/guide-ru/driver-file.md deleted file mode 100644 index f4f63f49..00000000 --- a/docs/guide-ru/driver-file.md +++ /dev/null @@ -1,65 +0,0 @@ -Файловый драйвер -================ - -Файловый драйвер для хранения очереди заданий использует определенную директорию. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\file\Queue::class, - 'path' => '@runtime/queue', - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen [delay] -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. `timeout` - время -ожидания в секундах перед следующим опросом очереди. Способ наиболее эффективен, если запускать -команду через [Supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через [cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. - -```sh -yii queue/info -``` - -Команда `info` выводит информацию о состоянии очереди. - -```sh -yii queue/clear -``` - -Команда `clear` делает полную очистку очереди. - -```sh -yii queue/remove [id] -``` - -Команда `remove` удаляет задание с указанным ID из очереди. diff --git a/docs/guide-ru/driver-gearman.md b/docs/guide-ru/driver-gearman.md deleted file mode 100644 index e4589122..00000000 --- a/docs/guide-ru/driver-gearman.md +++ /dev/null @@ -1,49 +0,0 @@ -Gearman драйвер -=============== - -Драйвер работает с очередью на базе Gearman. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\gearman\Queue::class, - 'host' => 'localhost', - 'port' => 4730, - 'channel' => 'my_queue', - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. Способ наиболее эфективен -если запускать команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через -[cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. diff --git a/docs/guide-ru/driver-redis.md b/docs/guide-ru/driver-redis.md deleted file mode 100644 index 26cce27a..00000000 --- a/docs/guide-ru/driver-redis.md +++ /dev/null @@ -1,73 +0,0 @@ -Драйвер для Redis -================= - -Этот драйвер для хранения очереди заданий использует Redis. - -В приложении должно быть установлено расширение `yiisoft/yii2-redis`. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'redis' => [ - 'class' => \yii\redis\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'redis' => 'redis', // Компонент подключения к Redis или его конфиг - 'channel' => 'queue', // Ключ канала очереди - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen [timeout] -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. `timeout` - время -ожидания задания из очереди перед следующей итерацией. Способ наиболее эфективен если запускать -команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через -[cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. - -```sh -yii queue/info -``` - -Команда `info` выводит информацию о состоянии очереди. - -```sh -yii queue/clear -``` - -Команда `clear` делает полную очистку очереди. - -```sh -yii queue/remove [id] -``` - -Команда `remove` удаляет задание из очереди. diff --git a/docs/guide-ru/driver-sqs.md b/docs/guide-ru/driver-sqs.md deleted file mode 100644 index 3cbc7cb0..00000000 --- a/docs/guide-ru/driver-sqs.md +++ /dev/null @@ -1,65 +0,0 @@ -Драйвер для AWS SQS -================= - -Этот драйвер для хранения очереди заданий использует AWS SQS. - -В приложении должно быть установлено расширение `aws/aws-sdk-php`. - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\sqs\Queue::class, - 'url' => '', - 'key' => '', - 'secret' => '', - 'region' => '', - ], - ], -]; -``` - -Консоль -------- - -Для обработки очереди используются консольные команды. - -```sh -yii queue/listen [timeout] -``` - -Команда `listen` запускает обработку очереди в режиме демона. Очередь опрашивается непрерывно. -Если добавляются новые задания, то они сразу же извлекаются и выполняются. `timeout` - время -ожидания задания из очереди перед следующей итерацией. `listen` использует функцию "Long Polling", -которая удерживает соединение с очередью и прослушивает ее на появление новых сообщений. - -**Важно!** Параметр`timeout` для драйвера AWS SQS должен быть в интервале от 0 до 20 секунд. - -Способ наиболее эфективен если запускать -команду через [supervisor](worker.md#supervisor) или [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -Команда `run` в цикле извлекает задания из очереди и выполняет их, пока очередь не опустеет, и -завершает свою работу. Это способ подойдет для обработки очереди заданий через -[cron](worker.md#cron). - -Для команд `run` и `listen` доступны следующие опции: - -- `--verbose`, `-v`: состояние обработки заданий выводится в консоль. -- `--isolate`: каждое задание выполняется в отдельном дочернем процессе. -- `--color`: подсветка вывода в режиме `--verbose`. - - -```sh -yii queue/clear -``` - -Команда `clear` делает полную очистку очереди. diff --git a/docs/guide-ru/driver-sync.md b/docs/guide-ru/driver-sync.md deleted file mode 100644 index a7c64551..00000000 --- a/docs/guide-ru/driver-sync.md +++ /dev/null @@ -1,18 +0,0 @@ -Синхронный драйвер -================== - -Этот драйвер выполняет задания синхронно, в том же сеансе, если установлен флаг `handle`. Драйвер -может использоваться на этапе разработки и отладки приложения. - -Настройка драйвера: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Sync\Queue::class, - 'handle' => false, // Флаг необходимости выполнять поставленные в очередь задания - ], - ], -]; -``` diff --git a/docs/guide-ru/gii.md b/docs/guide-ru/gii.md deleted file mode 100644 index 9e9c3ea6..00000000 --- a/docs/guide-ru/gii.md +++ /dev/null @@ -1,28 +0,0 @@ -Генератор кода Gii -================== - -Для создания заданий воркерам можно воспользоваться генератором кода. - -Настройка ---------- - -Чтобы использовать раздел `job` в своем проекте, необходимо дополнить конфигурацию (например, `backend/config/main-local.php`) следующим образом: - -```php -if (!YII_ENV_TEST) { - $config['bootstrap'][] = 'gii'; - $config['modules']['gii'] = [ - 'class' => 'Yiisoft\Yii\Gii\Module', - 'generators' => [ - 'job' => [ - 'class' => \Yiisoft\Yii\Queue\Gii\Generator::class, - ], - ], - ]; -} - -``` - -После чего генератор кода для заданий будет добавлен в меню. - -![default](https://user-images.githubusercontent.com/1656851/29426628-e9a3e5ae-838f-11e7-859f-6f3cb8649f02.png) diff --git a/docs/guide-ru/retryable.md b/docs/guide-ru/retryable.md deleted file mode 100644 index 2fe296d3..00000000 --- a/docs/guide-ru/retryable.md +++ /dev/null @@ -1,122 +0,0 @@ -Ошибки и повторное выполнение -============================= - -В процессе обработки заданий могут возникать исключительные ситуации. Это могут быть как внутренние -ошибки — результат криво написанного кода, так и внешние - когда запрашиваемые сервисы и внешние -ресурсы временно недоступны. Во втором случае неплохо иметь возможность повторить попытку выполнить -задание через некоторое время. - -Для того чтобы это сделать существует несколько способов. - - -Опции повторного выполнения ---------------------------- - -Первый способ реализован глобальными настройками компонента: - -```php -'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'ttr' => 5 * 60, // Максимальное время выполнения задания - 'attempts' => 3, // Максимальное кол-во попыток - ], -], -``` - -Опция `ttr` устанавливает резервное время для выполнения заданий. Перед выполнением задание попадает -в резерв и будет находиться там не дольше чем задано в `ttr`. Если задание не выполнилось успешно, -и требуется повторная попытка, оно вернется назад в очередь. Если выполнилось - будет удалено -из резерва. Опция `attempts` устанавливает максимальное количество попыток. Если попытки закончились, -и задание не выполнилось удачно, оно так же будет удалено из резерва. - -Устанавливая опцию `ttr`, важно учесть, чтобы этого времени было достаточно, иначе воркер убьет процесс -выполняющегося задания по таймауту прямо во время выполнения. - -Описанные опции действуют глобально на все задания в очереди. Чтобы переопределить поведение для отдельных -заданий, существуют дополнительные возможности. - - -RetryableJobInterface ---------------------- - -Индивидуальный контроль повторного выполнения реализован интерфейсом `RetryableJobInterface`, код -такого job-объекта может выглядеть следующим образом: - -```php -class SomeJob extends BaseObject implements RetryableJobInterface -{ - public function execute($queue) - { - //... - } - - public function getTtr() - { - return 15 * 60; - } - - public function canRetry($attempt, $error) - { - return ($attempt < 5) && ($error instanceof TemporaryException); - } -} -``` - -Методы `getTtr()` и `canRetry()` имеют более высокий приоритет, чем общие настройки очереди, и дают -возможность реализовать индивидуальный алгоритм повторного выполнения задачи, если предыдущая попытка -завершилась неудачей. - - -Обработчики событий -------------------- - -Еще один способ задать резервное время и необходимость повторного запуска невыполненной задачи -предполагает использование событий `Queue::EVENT_BEFORE_PUSH` и `Queue::EVENT_AFTER_ERROR`. - -Событие `Queue::EVENT_BEFORE_PUSH` можно использовать, чтобы задать резервное время: - -```php -Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) { - if ($event->job instanceof SomeJob) { - $event->ttr = 300; - } -}); -``` - -А событие `Queue::EVENT_AFTER_ERROR` — чтобы определить задание на повторную попытку: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) { - if ($event->job instanceof SomeJob) { - $event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException); - } -}); -``` - -Обработчики событий выполняются после методов `RetryableJobInterface` и, следовательно, имеют -наивысший приоритет. - - -Ограничения ------------ - -Не все драйверы одинаково хорошо поддерживают повторное выполнение заданий. Полноценную поддержку -обеспечивают драйвера: [Beanstalk], [DB], [File] и [Redis]. [Синхронный драйвер], как отладочный, -не будет повторять невыполненные задания. [Gearman] не поддерживает повторное выполнение вообще. -А [RabbitMQ] имеет только свою базовую поддержку повторов, при которой номер попытки узнать -не получится. - -В [AWS SQS] для обработки сообщений, которые не могут быть обработаны, используется [Dead Letter очередь]. -В эту очередь попадают сообщения, которые не обработались после максимального количества попыток. -Указать Dead Letter очередь и максимальное количество попыток можно при создании очереди через консоль AWS. - -[Beanstalk]: driver-beanstalk.md -[DB]: driver-db.md -[File]: driver-file.md -[Redis]: driver-redis.md -[Синхронный драйвер]: driver-sync.md -[Gearman]: driver-gearman.md -[RabbitMQ]: driver-amqp.md -[AWS SQS]: driver-sqs.md -[Dead Letter очередь]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html diff --git a/docs/guide-ru/usage.md b/docs/guide-ru/usage.md deleted file mode 100644 index 13e464ad..00000000 --- a/docs/guide-ru/usage.md +++ /dev/null @@ -1,257 +0,0 @@ -Основы использования -==================== - - -Настройка ---------- - -Чтобы использовать расширение в своем проекте, необходимо дополнить конфигурацию следующим образом: - -```php -return [ - 'bootstrap' => [ - 'queue', // Компонент регистрирует свои консольные команды - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class, - // Индивидуальные настройки драйвера - ], - ], -]; -``` - -Список доступных драйверов и инструкции по их настройке можно посмотреть в [содержании](README.md). - - -Использование в коде --------------------- - -Каждое задание, которое Вы планируете отправлять в очередь, оформляется в виде отдельного класса. -Например, если нужно скачать и сохранить файл, класс может выглядеть так: - -```php -class DownloadJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $url; - public $file; - - public function execute($queue) - { - file_put_contents($this->file, file_get_contents($this->url)); - } -} -``` - -Отправить задание в очередь можно с помощью кода: - -```php -Yii::$app->queue->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` - -Отправить задание для выполнения с задержкой в 5 минут: - -```php -Yii::$app->queue->delay(5 * 60)->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` - -**Внимание:** Драйвера RabbitMQ и Gearman не поддерживают отложенные задания. - - -Обработка очереди ------------------ - -Способы обработки очереди задач могут различаться, и зависят от используемого драйвера. В большей -части драйверов воркеры запускаются с помощью консольных команд, которые компонент сам регистрирует -в приложении. Детальное описание смотрите в документации конкретного драйвера. - - -Статус заданий --------------- - -Компонент дает возможность отслеживать состояние поставленных в очередь заданий. - -```php -// Отправляем задание в очередь, и получаем его ID. -$id = Yii::$app->queue->push(new SomeJob()); - -// Задание еще находится в очереди. -Yii::$app->queue->isWaiting($id); - -// Воркер взял задание из очереди, и выполняет его. -Yii::$app->queue->isReserved($id); - -// Воркер уже выполнил задание. -Yii::$app->queue->isDone($id); -``` - -**Внимание:** Драйвера RabbitMQ и AWS SQS не поддерживает статусы. - - -Сообщения для сторонних воркеров --------------------------------- - -В очередь можно передавать гибридные данные, например: - -```php -Yii::$app->queue->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - -Это допустимо, если очередь обрабатывается сторонним воркером, разработанным индивидуально. - -Если воркер разрабатывается не на PHP, то, также, необходимо изменить способ сериализации данных, -чтобы сообщения кодировались доступным воркеру форматом. Например, настроить сериализацию в json, -самым простым способом, можно так: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -Обработка событий ------------------ - -Очередь триггерит следующие события: - -| Событие | Класс события | Когда триггерится | -|------------------------------|---------------|---------------------------------------------------------------| -| Queue::EVENT_BEFORE_PUSH | PushEvent | Добавление задания в очередь используя метод `Queue::push()` | -| Queue::EVENT_AFTER_PUSH | PushEvent | Добавление задания в очередь используя метод `Queue::push()` | -| Queue::EVENT_BEFORE_EXEC | ExecEvent | Перед каждым выполнением задания | -| Queue::EVENT_AFTER_EXEC | ExecEvent | После каждого успешного выполнения задания | -| Queue::EVENT_AFTER_ERROR | ExecEvent | Если при выполнение задания случилось непойманное исключение | -| cli\Queue:EVENT_WORKER_START | WorkerEvent | В момент запуска нового воркера | -| cli\Queue:EVENT_WORKER_LOOP | WorkerEvent | В цикле между опросами очереди | -| cli\Queue:EVENT_WORKER_STOP | WorkerEvent | В момент остановки воркера | - -Вы с лёгкостью можете подключить свой собственный слушатель на любое из этих событий. -Например, давайте отложим выполнение задания, которое выбросило специальное исключение: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function ($event) { - if ($event->error instanceof TemporaryUnprocessableJobException) { - $queue = $event->sender; - $queue->delay(7200)->push($event->job); - } -}); -``` - -Логирование событий -------------------- - -Этот компонент предоставляет `LogBehavior` для логирования событий, используя -[встроенный в Yii логгер](http://www.yiiframework.com/doc-2.0/guide-runtime-logging.html). - -Чтобы использовать его, просто подключите это поведение в конфигурации компонента, как показано в -примере: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class - ], - ], -]; -``` - -Несколько очередей ------------------- - -Пример настройки: - -```php -return [ - 'bootstrap' => [ - 'queue1', // Первый компонент регистрирует свои консольные команды - 'queue2', // Второй - свои - ], - 'components' => [ - 'queue1' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - ], - 'queue2' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -Пример использования: - -```php -// Отправка задания в очередь для обработки встроенным воркером -Yii::$app->queue1->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); - -// Отправка сообщения в другую очередь для обработки сторонним воркером -Yii::$app->queue2->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - -Ограничения ------------ - -Используя очереди важно помнить, что задачи ставятся и извлекаются из очереди в разных процессах. -Поэтому, при обработке задания, избегайте использования внешних зависимостей, когда не уверены -в том, что они будут доступны в окружении, где работает воркер. - -Все данные, необходимые для выполнения задания, нужно оформлять в виде свойств Вашего job-объекта, -и отправлять в очередь вместе с ним. - -Если в задании нужно работать с моделью `ActiveRecord`, вместо самой модели передавайте ее ID. А в -момент выполнения извлекайте ее из базы данных. - -Например: - -```php -Yii::$app->queue->push(new SomeJob([ - 'userId' => Yii::$app->user->id, - 'bookId' => $book->id, - 'someUrl' => Url::to(['controller/action']), -])); -``` - -Класс задания: - -```php -class SomeJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $userId; - public $bookId; - public $someUrl; - - public function execute($queue) - { - $user = User::findOne($this->userId); - $book = Book::findOne($this->bookId); - //... - } -} -``` diff --git a/docs/guide-ru/worker.md b/docs/guide-ru/worker.md deleted file mode 100644 index c425cb92..00000000 --- a/docs/guide-ru/worker.md +++ /dev/null @@ -1,125 +0,0 @@ -Управление запуском воркеров -============================ - - -Supervisor ----------- - -Supervisor — монитор процессов для ОС Linux. Он автоматически перезапустит ваши консольные процессы, -если они остановятся. Для установки Supervisor в Ubuntu можно использовать следующую команду: - -```sh -sudo apt-get install supervisor -``` - -Конфиги Supervisor обычно находятся в папке `/etc/supervisor/conf.d`. Можно создать любое количество -конфигов. - -Пример конфига: - -```conf -[program:yii-queue-worker] -process_name=%(program_name)s_%(process_num)02d -command=/usr/bin/php /var/www/my_project/yii queue/listen --verbose=1 --color=0 -autostart=true -autorestart=true -user=www-data -numprocs=4 -redirect_stderr=true -stdout_logfile=/var/www/my_project/log/yii-queue-worker.log -``` - -Этот пример указывает, что Supervisor должен запустить 4 воркера `queue/listen`, наблюдать за ними, -и автоматически перезапускать их если они будут падать. Весь вывод будет писаться в лог. - -Подробнее о настройке и использовании Supervisor читайте в [документации](http://supervisord.org). - -Запуск воркера в режиме демона командой `queue/listen` поддерживают драйвера [File], [Db], [Redis], -[RabbitMQ], [Beanstalk], [Gearman], [AWS SQS]. Дополнительные опции смотрите в описании нужных вам драйверов. - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[RabbitMQ]: driver-amqp.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md -[AWS SQS]: driver-sqs.md - - -Systemd -------- - -Systemd - система Linux для инициализации демонов. Чтобы настроить запуск воркеров под управлением systemd, -создайте конфиг с именем `yii-queue@.service` в папке `/etc/systemd/system` со следующими настройками: - -```conf -[Unit] -Description=Yii Queue Worker %I -After=network.target -# Ниже указана зависимость от mysql. Это справедливо если вы используте очереди на основе mysql. -# Если ваш проект использует другой брокер очередей, нужно изменить или дополнить эту секцию. -After=mysql.service -Requires=mysql.service - -[Service] -User=www-data -Group=www-data -ExecStart=/usr/bin/php /var/www/my_project/yii queue/listen --verbose -Restart=on-failure - -[Install] -WantedBy=multi-user.target -``` - -Перезагрузите systemd, чтобы он увидел новый конфиг, с помощью команды: - -```sh -systemctl daemon-reload -``` - -Набор команд для управления воркерами: - -```sh -# Запустить два воркера -systemctl start yii-queue@1 yii-queue@2 - -# Получить статус запущенных воркеров -systemctl status "yii-queue@*" - -# Остановить один воркер -systemctl stop yii-queue@2 - -# Остановить все воркеры -systemctl stop "yii-queue@*" - -# Добавить воркеры в автозагрузку -systemctl enable yii-queue@1 yii-queue@2 -``` - -Чтобы ознакомиться со всеми возможностями systemd, и сделать более тонкую настройку, смотрите -[документацию](https://freedesktop.org/wiki/Software/systemd/#manualsanddocumentationforusersandadministrators). - - -Cron ----- - -Запускать воркеры можно с помощью cron. Для этого удобнее всего использовать команду `queue/run`. -Она будет работать, пока в очереди есть задания. - -Пример настройки: - -```sh -* * * * * /usr/bin/php /var/www/my_project/yii queue/run -``` - -В этом случае cron будет запускать команду каждую минуту. - -Команду `queue/run` поддерживают драйвера [File], [Db], [Redis], [Beanstalk], [Gearman], [AWS SQS]. -Дополнительные опции смотрите в описании нужных вам драйверов. - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md -[AWS SQS]: driver-sqs.md diff --git a/docs/guide-zh-CN/README.md b/docs/guide-zh-CN/README.md deleted file mode 100644 index ab406926..00000000 --- a/docs/guide-zh-CN/README.md +++ /dev/null @@ -1,24 +0,0 @@ -Yii2 队列扩展 -==================== - -通过这个队列扩展可以异步执行任务 - -介绍 ------------- - -* [基本使用](usage.md) -* [错误与重试作业](retryable.md) -* [Worker starting control](worker.md) -* [调试](debug.md) - -队列驱动 -------------- - -* [Syncronous](driver-sync.md) -* [File](driver-file.md) -* [Db](driver-db.md) -* [Redis](driver-redis.md) -* [RabbitMQ](driver-amqp.md) -* [AMQP Interop](driver-amqp-interop.md) -* [Beanstalk](driver-beanstalk.md) -* [Gearman](driver-gearman.md) diff --git a/docs/guide-zh-CN/debug.md b/docs/guide-zh-CN/debug.md deleted file mode 100644 index 35198906..00000000 --- a/docs/guide-zh-CN/debug.md +++ /dev/null @@ -1,22 +0,0 @@ -调试 -========= - -为了使开发过程更加友好，您可以向Yii2调试模块添加一个面板。面板显示 -计数器和队列任务列表。 - -`yiisoft/yii2-debug` 应该安装在你的应用程序中，以便在调试面板中显示 - -将您的应用程序配置如下： - -```php -return [ - 'modules' => [ - 'debug' => [ - 'class' => \yii\debug\Module::class, - 'panels' => [ - 'queue' => \Yiisoft\Yii\Queue\Debug\Panel::class, - ], - ], - ], -]; -``` diff --git a/docs/guide-zh-CN/driver-amqp-interop.md b/docs/guide-zh-CN/driver-amqp-interop.md deleted file mode 100644 index 17fb5d80..00000000 --- a/docs/guide-zh-CN/driver-amqp-interop.md +++ /dev/null @@ -1,67 +0,0 @@ -AMQP Interop -============ - -The driver works with RabbitMQ queues. - -In order for it to work you should add any [amqp interop](https://github.com/queue-interop/queue-interop#amqp-interop) compatible transport to your project, for example `enqueue/amqp-lib` package. - -Advantages: - -* It would work with any amqp interop compatible transports, such as - - * [enqueue/amqp-ext](https://github.com/php-enqueue/amqp-ext) based on [PHP amqp extension](https://github.com/pdezwart/php-amqp) - * [enqueue/amqp-lib](https://github.com/php-enqueue/amqp-lib) based on [php-amqplib/php-amqplib](https://github.com/php-amqplib/php-amqplib) - * [enqueue/amqp-bunny](https://github.com/php-enqueue/amqp-bunny) based on [bunny](https://github.com/jakubkulhan/bunny) - -* Supports priorities -* Supports delays -* Supports ttr -* Supports attempts -* Contains new options like: vhost, connection_timeout, qos_prefetch_count and so on. -* Supports Secure (SSL) AMQP connections. -* An ability to set DSN like: amqp:, amqps: or amqp://user:pass@localhost:1000/vhost - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Interop\Queue::class, - 'port' => 5672, - 'user' => 'guest', - 'password' => 'guest', - 'queueName' => 'queue', - 'driver' => Yiisoft\Yii\Queue\Drivers\Interop\Queue::ENQUEUE_AMQP_LIB, - - // or - 'dsn' => 'amqp://guest:guest@localhost:5672/%2F', - - // or, same as above - 'dsn' => 'amqp:', - ], - ], -]; -``` - -Console -------- - -Console is used to listen and process queued tasks. - -```sh -yii queue/listen -``` - -`listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. This method is most efficient when command is properly -daemonized via [supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -`listen` command has options: - -- `--verbose`, `-v`: print executing statuses into console. -- `--isolate`: verbose mode of a job execute. If enabled, execute result of each job will be printed. -- `--color`: highlighting for verbose mode. diff --git a/docs/guide-zh-CN/driver-beanstalk.md b/docs/guide-zh-CN/driver-beanstalk.md deleted file mode 100644 index 6677815c..00000000 --- a/docs/guide-zh-CN/driver-beanstalk.md +++ /dev/null @@ -1,58 +0,0 @@ -Beanstalk 驱动 -================ - -驱动程序使用 Beanstalk 队列。 - -配置示例: - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\beanstalk\Queue::class, - 'host' => 'localhost', - 'port' => 11300, - 'tube' => 'queue', - ], - ], -]; -``` - -控制台 -------- - -控制台用于监听和处理队列任务。 - -```sh -yii queue/listen [timeout] -``` - -`listen` 命令启动一个守护进程，它可以无限查询队列。如果有新的任务，他们立即得到并执行。 -`timeout` 是下一次查询队列的时间 当命令正确地通过[supervisor](worker.md#supervisor)来实现时，这种方法是最有效的。 - -```sh -yii queue/run -``` - -`run` 命令获取并执行循环中的任务，直到队列为空。适用与[cron](worker.md#cron)。 - -`run` 与 `listen` 命令的参数: - -- `--verbose`, `-v`: 将执行状态输出到控制台。 -- `--isolate`: 详细模式执行作业。如果启用，将打印每个作业的执行结果。 -- `--color`: 高亮显示输出结果。 - -```sh -yii queue/info -``` - -`info` 命令打印关于队列状态的信息。 - -```sh -yii queue/remove [id] -``` - -`remove` command removes a job. diff --git a/docs/guide-zh-CN/driver-db.md b/docs/guide-zh-CN/driver-db.md deleted file mode 100644 index 61107903..00000000 --- a/docs/guide-zh-CN/driver-db.md +++ /dev/null @@ -1,114 +0,0 @@ -DB 驱动 -========= - -DB 驱动使用库存储队列数据 - -配置示例: - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'db' => [ - 'class' => \Yiisoft\Db\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'db' => 'db', // DB 连接组件或它的配置 - 'tableName' => '{{%queue}}', // 表名 - 'channel' => 'default', // Queue channel key - 'mutex' => \Yiisoft\Mutex\MysqlMutex::class, // Mutex that used to sync queries - ], - ], -]; -``` - -您必须向数据库添加一个表。MySQL示例语句: - -```SQL -CREATE TABLE `queue` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `channel` varchar(255) NOT NULL, - `job` blob NOT NULL, - `pushed_at` int(11) NOT NULL, - `ttr` int(11) NOT NULL, - `delay` int(11) NOT NULL DEFAULT 0, - `priority` int(11) unsigned NOT NULL DEFAULT 1024, - `reserved_at` int(11) DEFAULT NULL, - `attempt` int(11) DEFAULT NULL, - `done_at` int(11) DEFAULT NULL, - PRIMARY KEY (`id`), - KEY `channel` (`channel`), - KEY `reserved_at` (`reserved_at`), - KEY `priority` (`priority`) -) ENGINE=InnoDB -``` - -迁移文件存放在 [src/drivers/db/migrations](../../src/drivers/db/migrations). - -添加迁移到您的应用程序，编辑控制台配置文件以配置[命名空间迁移](http://www.yiiframework.com/doc-2.0/guide-db-migrations.html#namespaced-migrations): - -```php -'controllerMap' => [ - // ... - 'migrate' => [ - 'class' => 'Yiisoft\Yii\Console\Controllers\MigrateController', - 'migrationPath' => null, - 'migrationNamespaces' => [ - // ... - 'Yiisoft\Yii\Queue\Drivers\Db\migrations', - ], - ], -], -``` - -然后使用迁移命令: - -```sh -yii migrate/up -``` - -控制台 -------- - -控制台用于监听和处理队列任务。 - -```sh -yii queue/listen [timeout] -``` - -`listen` 命令启动一个守护进程，它可以无限查询队列。如果有新的任务，他们立即得到并执行。 -`timeout` 是下一次查询队列的时间 当命令正确地通过[supervisor](worker.md#supervisor)来实现时，这种方法是最有效的。 - -```sh -yii queue/run -``` - -`run` 命令获取并执行循环中的任务，直到队列为空。适用与[cron](worker.md#cron)。 - -`run` 与 `listen` 命令的参数: - -- `--verbose`, `-v`: 将执行状态输出到控制台。 -- `--isolate`: 详细模式执行作业。如果启用，将打印每个作业的执行结果。 -- `--color`: 高亮显示输出结果。 - -```sh -yii queue/info -``` - -`info` 命令打印关于队列状态的信息。 - -```sh -yii queue/clear -``` - -`clear` command clears a queue. - -```sh -yii queue/remove [id] -``` - -`remove` command removes a job. diff --git a/docs/guide-zh-CN/driver-file.md b/docs/guide-zh-CN/driver-file.md deleted file mode 100644 index 5bf32aba..00000000 --- a/docs/guide-zh-CN/driver-file.md +++ /dev/null @@ -1,62 +0,0 @@ -File 驱动 -=========== - -File 驱动使用文件来存储队列数据。 - -配置示例: - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\file\Queue::class, - 'path' => '@runtime/queue', - ], - ], -]; -``` - -控制台 -------- - -控制台用于监听和处理队列任务。 - -```sh -yii queue/listen [timeout] -``` - -`listen` 命令启动一个守护进程，它可以无限查询队列。如果有新的任务，他们立即得到并执行。 -`timeout` 是下一次查询队列的时间 当命令正确地通过[supervisor](worker.md#supervisor)来实现时，这种方法是最有效的。 - -```sh -yii queue/run -``` - -`run` 命令获取并执行循环中的任务，直到队列为空。适用与[cron](worker.md#cron)。 - -`run` 与 `listen` 命令的参数: - -- `--verbose`, `-v`: 将执行状态输出到控制台。 -- `--isolate`: 详细模式执行作业。如果启用，将打印每个作业的执行结果。 -- `--color`: 高亮显示输出结果。 - -```sh -yii queue/info -``` - -`info` 命令打印关于队列状态的信息。 - -```sh -yii queue/clear -``` - -`clear` command clears a queue. - -```sh -yii queue/remove [id] -``` - -`remove` command removes a job. diff --git a/docs/guide-zh-CN/driver-gearman.md b/docs/guide-zh-CN/driver-gearman.md deleted file mode 100644 index d8ebf184..00000000 --- a/docs/guide-zh-CN/driver-gearman.md +++ /dev/null @@ -1,48 +0,0 @@ -Gearman 驱动 -============== - -驱动程序使用 Gearman 队列。 - -配置示例: - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\gearman\Queue::class, - 'host' => 'localhost', - 'port' => 4730, - 'channel' => 'my_queue', - ], - ], -]; -``` - -控制台 -------- - -控制台用于监听和处理队列任务。 - -```sh -yii queue/listen -``` - -`listen` 命令启动一个守护进程，它可以无限查询队列。如果有新任务的话它们立即得到并执行。 -当命令正确地通过[supervisor](worker.md#supervisor)来实现时，这种方法是最有效 。 - -```sh -yii queue/run -``` - -`run` 命令获取并执行循环中的任务，直到队列为空。适用与[cron](worker.md#cron)。 - -`run` 与 `listen` 命令的参数: - -- `--verbose`, `-v`: 将执行状态输出到控制台。 -- `--isolate`: 详细模式执行作业。如果启用，将打印每个作业的执行结果。 -- `--color`: 高亮显示输出结果。 - - diff --git a/docs/guide-zh-CN/driver-redis.md b/docs/guide-zh-CN/driver-redis.md deleted file mode 100644 index 12138258..00000000 --- a/docs/guide-zh-CN/driver-redis.md +++ /dev/null @@ -1,69 +0,0 @@ -Redis 驱动 -============ - -驱动程序使用Redis存储队列数据。 - -您需要添加 `yiisoft/yii2-redis` 扩展到你的应和中。 - -配置示例: - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'redis' => [ - 'class' => \yii\redis\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'redis' => 'redis', // 连接组件或它的配置 - 'channel' => 'queue', // Queue channel key - ], - ], -]; -``` - -控制台 -------- - -控制台用于监听和处理队列任务。 - -```sh -yii queue/listen [timeout] -``` - -`listen` 命令启动一个守护进程，它可以无限查询队列。如果有新的任务，他们立即得到并执行。 -`timeout` 是下一次查询队列的时间 当命令正确地通过[supervisor](worker.md#supervisor)来实现时，这种方法是最有效的。 - -```sh -yii queue/run -``` - -`run` 命令获取并执行循环中的任务，直到队列为空。适用与[cron](worker.md#cron)。 - -`run` 与 `listen` 命令的参数: - -- `--verbose`, `-v`: 将执行状态输出到控制台。 -- `--isolate`: 详细模式执行作业。如果启用，将打印每个作业的执行结果。 -- `--color`: 高亮显示输出结果。 - -```sh -yii queue/info -``` - -`info` 命令打印关于队列状态的信息。 - -```sh -yii queue/clear -``` - -`clear` command clears a queue. - -```sh -yii queue/remove [id] -``` - -`remove` command removes a job. diff --git a/docs/guide-zh-CN/driver-sync.md b/docs/guide-zh-CN/driver-sync.md deleted file mode 100644 index 9f570769..00000000 --- a/docs/guide-zh-CN/driver-sync.md +++ /dev/null @@ -1,18 +0,0 @@ -Syncronous 驱动 -================= - -如果打开 `handle`属性，则在使用过程中同步运行任务。 -一般在开发和调试应用程序时使用。 - -配置示例: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Sync\Queue::class, - 'handle' => false, // 任务是否立即执行 - ], - ], -]; -``` diff --git a/docs/guide-zh-CN/retryable.md b/docs/guide-zh-CN/retryable.md deleted file mode 100644 index 7767d8ea..00000000 --- a/docs/guide-zh-CN/retryable.md +++ /dev/null @@ -1,98 +0,0 @@ -错误与重复执行 -========================= - -在作业处理期间可以抛出异常。 当请求的服务和外部资源不可用时，由于代码编写的比较糟糕而导致的内部错误。 -在第二种情况下，可以在一段时间后重新尝试这个作业。 - -有几种方法可以做到这一点。 - -重试选项 -------------- - -第一个方法由组件选项实现: - -```php -'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'ttr' => 5 * 60, // Max time for anything job handling - 'attempts' => 3, // Max number of attempts - ], -], -``` - - `ttr` 选项设置了在队列中保留工作的时间。如果一份作业在这段时间没有执行，它将返回队列进行重试。 - `attempts` 选项设置了最大的尝试次数。如果尝试已经结束，作业作还没有完成，它将从队列中移除。 - -这种将全局设置队列中的所有作业，如果您需要为多个作业进行不同的设置可以使用， -第二种方法。 - -重试作业接口 ----------------------- - -Separate control of retry is implemented by `RetryableJobInterface` 接口。 示例: - -```php -class SomeJob extends BaseObject implements RetryableJobInterface -{ - public function execute($queue) - { - //... - } - - public function getTtr() - { - return 15 * 60; - } - - public function canRetry($attempt, $error) - { - return ($attempt < 5) && ($error instanceof TemporaryException); - } -} -``` - -`getTtr()` 与 `canRetry()` 方法比组件配置有更高的优先级。 - -事件处理 --------------- - -第三种方法设置TTR和需要重试失败的作业包括使用 -`Queue::EVENT_BEFORE_PUSH` 与 `Queue::EVENT_AFTER_ERROR` 事件。 - -`Queue::EVENT_BEFORE_PUSH` 事件可用于设置TTR: - -```php -Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) { - if ($event->job instanceof SomeJob) { - $event->ttr = 300; - } -}); -``` - -并且 `Queue::EVENT_AFTER_ERROR` 事件可用于设置新的尝试: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) { - if ($event->job instanceof SomeJob) { - $event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException); - } -}); -``` - -事件处理程序在 `RetryableJobInterface` 方法之后执行，因此具有最高优先级。 - -限制 ------------- - -完全支持 [Beanstalk], [DB], [File] 和 [Redis] 驱动程序的重试工具。 -[Sync] 驱动不会重试失败的工作 [Gearman] 不支持重试。 -[RabbitMQ] 基本版支持，但重试编号无法得到。 - -[Beanstalk]: driver-beanstalk.md -[DB]: driver-db.md -[File]: driver-file.md -[Redis]: driver-redis.md -[Sync]: driver-sync.md -[Gearman]: driver-gearman.md -[RabbitMQ]: driver-amqp.md diff --git a/docs/guide-zh-CN/usage.md b/docs/guide-zh-CN/usage.md deleted file mode 100644 index d1ee4639..00000000 --- a/docs/guide-zh-CN/usage.md +++ /dev/null @@ -1,250 +0,0 @@ -基本使用 -============ - - -配置 -------------- - -如果要使用这个扩展必须向下面这样配置它 - -```php -return [ - 'bootstrap' => [ - 'queue', // 把这个组件注册到控制台 - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class, - // 驱动的其他选项 - ], - ], -]; -``` - -可用的驱动程序列表及其配置文档在[README](README.md)目录中. - -在代码中使用 -------------- - -每个被发送到队列的任务应该被定义为一个单独的类。 -例如，如果您需要下载并保存一个文件，该类可能看起来如下: - -```php -class DownloadJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $url; - public $file; - - public function execute($queue) - { - file_put_contents($this->file, file_get_contents($this->url)); - } -} -``` - -下面是将任务添加到队列: - -```php -Yii::$app->queue->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` -将作业推送到队列中延时5分钟运行: - -```php -Yii::$app->queue->delay(5 * 60)->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); -``` - -**重要:** 只有一部分驱动支持延时运行。 - - -处理队列 --------------- - -具体执行任务的方式取决于所使用的驱动程序。大多数驱动都可以使用 -控制台命令，组件在您的应用程序中注册。有关更多细节，请参见相关驱动文档 -。 - - -作业状态 ----------- - -该组件具有跟踪被推入队列的作业状态的能力。 - -```php -// 将作业推送到队列并获得其ID -$id = Yii::$app->queue->push(new SomeJob()); - -// 这个作业等待执行。 -Yii::$app->queue->isWaiting($id); - -// Worker 从队列获取作业，并执行它。 -Yii::$app->queue->isReserved($id); - -// Worker 作业执行完成。 -Yii::$app->queue->isDone($id); -``` - -**Important:** RabbitMQ 驱动不支持作业状态。 - - -消息传递的第三方员工Messaging third party workers ------------------------------ - -您可以将任何数据传递给队列: - -```php -Yii::$app->queue->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` -如果使用的队列是第三方开发的，那么这是很有用的。 - -如果worker使用PHP以外的东西实现，那么您必须更改序列化数据的方式。例如, -JSON: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -事件处理 ---------------- - -队列可以触发以下事件: - -| Event name | Event class | Triggered on | -|------------------------------|-------------|-----------------------------------------------------------| -| Queue::EVENT_BEFORE_PUSH | PushEvent | Adding job to queue using `Queue::push()` method | -| Queue::EVENT_AFTER_PUSH | PushEvent | Adding job to queue using `Queue::push()` method | -| Queue::EVENT_BEFORE_EXEC | ExecEvent | Before each job execution | -| Queue::EVENT_AFTER_EXEC | ExecEvent | After each success job execution | -| Queue::EVENT_AFTER_ERROR | ExecEvent | When uncaught exception occurred during the job execution | -| cli\Queue:EVENT_WORKER_START | WorkerEvent | When worker has been started | -| cli\Queue:EVENT_WORKER_LOOP | WorkerEvent | Each iteration between requests to queue | -| cli\Queue:EVENT_WORKER_STOP | WorkerEvent | When worker has been stopped | - -您可以很容易地将自己的处理程序附加到这些事件中的任何一个。 -例如，如果它的执行失败了，那么让我们延迟它: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function ($event) { - if ($event->error instanceof TemporaryUnprocessableJobException) { - $queue = $event->sender; - $queue->delay(7200)->push($event->job); - } -}); -``` - -事件日志 --------------- - -此组件提供了使用日志 `LogBehavior` 记录队列事件 -[Yii built-in Logger](http://www.yiiframework.com/doc-2.0/guide-runtime-logging.html). - -要使用它，只需按照以下方式配置队列组件: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class - ], - ], -]; -``` - - -多个队列 ---------------- - -配置例子: - -```php -return [ - 'bootstrap' => [ - 'queue1', // 第一个组件注册了自己的控制台命令 - 'queue2', // 第二个组件注册了自己的控制台命令 - ], - 'components' => [ - 'queue1' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - ], - 'queue2' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -使用例子: - -```php -// 将任务发送到队列，通过标准工作人员进行处理 -Yii::$app->queue1->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); - -// 将任务发送到另一个队列，由第三方工作人员处理 -Yii::$app->queue2->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - - -限制 ------------ - -当使用队列时，务必记住，任务被放入队列中，并且在不同进程中从队列中获取。因此，如果您不确定在worker的作业环境中是否可用，则应在执行任务时避免外部依赖。 - -所有处理任务的数据都应该放到作业对象的属性中，并连同它一起发送到队列中。 - -如果您需要处理 `ActiveRecord` ，那么发送它的ID而不是对象本身。在处理时必须从DB提取它。 - -例如: - -```php -Yii::$app->queue->push(new SomeJob([ - 'userId' => Yii::$app->user->id, - 'bookId' => $book->id, - 'someUrl' => Url::to(['controller/action']), -])); -``` - -任务类: - -```php -class SomeJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $userId; - public $bookId; - public $someUrl; - - public function execute($queue) - { - $user = User::findOne($this->userId); - $book = Book::findOne($this->bookId); - //... - } -} -``` diff --git a/docs/guide-zh-CN/worker.md b/docs/guide-zh-CN/worker.md deleted file mode 100644 index 7fcdd920..00000000 --- a/docs/guide-zh-CN/worker.md +++ /dev/null @@ -1,117 +0,0 @@ -Worker starting control -======================= - -Supervisor ----------- - -Supervisor 是Linux的进程监视器。 -它会自动启动您的控制台进程。 -安装在Ubuntu上，你需要运行命令: - -```sh -sudo apt-get install supervisor -``` - -Supervisor 配置文件通常可用 `/etc/supervisor/conf.d`。 -你可以创建任意数量的配置文件。 - -配置示例: - -```conf -[program:yii-queue-worker] -process_name=%(program_name)s_%(process_num)02d -command=/usr/bin/php /var/www/my_project/yii queue/listen --verbose=1 --color=0 -autostart=true -autorestart=true -user=www-data -numprocs=4 -redirect_stderr=true -stdout_logfile=/var/www/my_project/log/yii-queue-worker.log -``` - -在这种情况下，Supervisor 会启动4个 `queue/listen` worker。输出将写入相应日志文件。 - -有关 Supervisor 配置和使用的更多信息，请参阅[文档](http://supervisord.org)。 - -以守护进程模式启动的Worker使用 `queue/listen` 命令支持 [File]、 [Db]、 [Redis]、 [RabbitMQ]、 [Beanstalk]、 [Gearman] 驱动。 有关其他参数，请参阅驱动程序指南。 - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[RabbitMQ]: driver-amqp.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md - -Systemd -------- - -Systemd is an init system used in Linux to bootstrap the user space. To configure workers startup -using systemd, create a config file named `yii-queue@.service` in `/etc/systemd/system` with -the following contents: - -```conf -[Unit] -Description=Yii Queue Worker %I -After=network.target -# the following two lines only apply if your queue backend is mysql -# replace this with the service that powers your backend -After=mysql.service -Requires=mysql.service - -[Service] -User=www-data -Group=www-data -ExecStart=/usr/bin/php /var/www/my_project/yii queue/listen --verbose -Restart=on-failure - -[Install] -WantedBy=multi-user.target -``` - -You need to reload systemd in order for it to re-read configuration: - -```sh -systemctl daemon-reload -``` - -Set of commands to control workers: - -```sh -# To start two workers -systemctl start yii-queue@1 yii-queue@2 - -# To get status of running workers -systemctl status "yii-queue@*" - -# To stop the worker -systemctl stop yii-queue@2 - -# To stop all running workers -systemctl stop "yii-queue@*" - -# To start two workers at system boot -systemctl enable yii-queue@1 yii-queue@2 -``` - -To learn all features of systemd, check its [documentation](https://freedesktop.org/wiki/Software/systemd/#manualsanddocumentationforusersandadministrators). - -Cron ----- - -您可以用cron开始worker。需要使用 `queue/run` 命令。只要队列包含作业，它就能进行执行。 - -配置示例: - -```sh -* * * * * /usr/bin/php /var/www/my_project/yii queue/run -``` - -在这种情况下，cron将每分钟启动一次命令。 - -`queue/run` 命令支持 [File]、[Db]、[Redis]、[Beanstalk]、[Gearman]驱动。有关其他选项，请参阅驱动程序指南。 - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md diff --git a/docs/guide/README.md b/docs/guide/README.md index ac898b68..19df674c 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,4 +1,4 @@ -Yii2 Queue extension +Yii3 Queue extension ==================== An extension for running tasks asynchronously via queues. @@ -14,17 +14,3 @@ Queue Drivers ------------- * [Synchronous](driver-sync.md) -* [File](driver-file.md) -* [Db](driver-db.md) -* [Redis](driver-redis.md) -* [RabbitMQ](driver-amqp.md) -* [AMQP Interop](driver-amqp-interop.md) -* [Beanstalk](driver-beanstalk.md) -* [Gearman](driver-gearman.md) -* [AWS SQS](driver-sqs.md) - -Developer tools ---------------- - -* [Debugging](debug.md) -* [Code generator Gii](gii.md) diff --git a/docs/guide/debug.md b/docs/guide/debug.md deleted file mode 100644 index d03a4cf4..00000000 --- a/docs/guide/debug.md +++ /dev/null @@ -1,22 +0,0 @@ -Debugging -========= - -During development you may want to add a panel for the Yii2 debug module. -The panel displays a counter and a list of queued tasks. - -The `yiisoft/yii2-debug` module should be installed in your application for the panel to be displayed. - -Configure your application like the following: - -```php -return [ - 'modules' => [ - 'debug' => [ - 'class' => \yii\debug\Module::class, - 'panels' => [ - 'queue' => \Yiisoft\Yii\Queue\Debug\Panel::class, - ], - ], - ], -]; -``` diff --git a/docs/guide/driver-amqp-interop.md b/docs/guide/driver-amqp-interop.md deleted file mode 100644 index 0cb85177..00000000 --- a/docs/guide/driver-amqp-interop.md +++ /dev/null @@ -1,62 +0,0 @@ -AMQP Interop -============ - -This driver works with RabbitMQ queues. - -It requires an [amqp interop](https://github.com/queue-interop/queue-interop#amqp-interop) compatible -transport, for example the `enqueue/amqp-lib` package. - -Advantages: - -* It works with any amqp interop compatible transports, such as - - * [enqueue/amqp-ext](https://github.com/php-enqueue/amqp-ext) based on [PHP amqp extension](https://github.com/pdezwart/php-amqp) - * [enqueue/amqp-lib](https://github.com/php-enqueue/amqp-lib) based on [php-amqplib/php-amqplib](https://github.com/php-amqplib/php-amqplib) - * [enqueue/amqp-bunny](https://github.com/php-enqueue/amqp-bunny) based on [bunny](https://github.com/jakubkulhan/bunny) - -* Supports priorities -* Supports delays -* Supports ttr -* Supports attempts -* Contains new options like: vhost, connection_timeout, qos_prefetch_count and so on. -* Supports Secure (SSL) AMQP connections. -* Has the ability to set DSN like: amqp:, amqps: or amqp://user:pass@localhost:1000/vhost - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Interop\Queue::class, - 'port' => 5672, - 'user' => 'guest', - 'password' => 'guest', - 'queueName' => 'queue', - 'driver' => Yiisoft\Yii\Queue\Drivers\Interop\Queue::ENQUEUE_AMQP_LIB, - - // or - 'dsn' => 'amqp://guest:guest@localhost:5672/%2F', - - // or, same as above - 'dsn' => 'amqp:', - ], - ], -]; -``` - -Console -------- - -A console command is used to execute queued jobs. - -```sh -yii queue/listen -``` - -The `listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. This method is most efficient when the command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). diff --git a/docs/guide/driver-beanstalk.md b/docs/guide/driver-beanstalk.md deleted file mode 100644 index 35a634ad..00000000 --- a/docs/guide/driver-beanstalk.md +++ /dev/null @@ -1,61 +0,0 @@ -Beanstalk Driver -================ - -This driver works with Beanstalk queues. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\beanstalk\Queue::class, - 'host' => 'localhost', - 'port' => 11300, - 'tube' => 'queue', - ], - ], -]; -``` - -Console -------- - -Console commands are used to execute and manage queued jobs. - -```sh -yii queue/listen [timeout] -``` - -The `listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. The `timeout` parameter specifies the number of seconds to sleep between -querying the queue. This method is most efficient when the command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -The `run` command obtains and executes tasks in a loop until the queue is empty. This works well with -[cron](worker.md#cron). - -The `run` and `listen` commands have options: - -- `--verbose`, `-v`: print execution status to console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: enable highlighting for verbose mode. - -```sh -yii queue/info -``` - -The `info` command prints out information about the queue status. - -```sh -yii queue/remove [id] -``` - -The `remove` command removes a job from the queue. diff --git a/docs/guide/driver-db.md b/docs/guide/driver-db.md deleted file mode 100644 index a8bad6f9..00000000 --- a/docs/guide/driver-db.md +++ /dev/null @@ -1,118 +0,0 @@ -DB Driver -========= - -The DB driver uses a database to store queue data. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'db' => [ - 'class' => \Yiisoft\Db\Connection::class, - // ... - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'db' => 'db', // DB connection component or its config - 'tableName' => '{{%queue}}', // Table name - 'channel' => 'default', // Queue channel key - 'mutex' => \Yiisoft\Mutex\MysqlMutex::class, // Mutex used to sync queries - ], - ], -]; -``` - -You have to add a table to the database. Example schema for MySQL: - -```SQL -CREATE TABLE `queue` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `channel` varchar(255) NOT NULL, - `job` blob NOT NULL, - `pushed_at` int(11) NOT NULL, - `ttr` int(11) NOT NULL, - `delay` int(11) NOT NULL DEFAULT 0, - `priority` int(11) unsigned NOT NULL DEFAULT 1024, - `reserved_at` int(11) DEFAULT NULL, - `attempt` int(11) DEFAULT NULL, - `done_at` int(11) DEFAULT NULL, - PRIMARY KEY (`id`), - KEY `channel` (`channel`), - KEY `reserved_at` (`reserved_at`), - KEY `priority` (`priority`) -) ENGINE=InnoDB -``` - -Migrations are available from [src/drivers/db/migrations](../../src/drivers/db/migrations). - -To add migrations to your application, edit the console config file to configure -[a namespaced migration](http://www.yiiframework.com/doc-2.0/guide-db-migrations.html#namespaced-migrations): - -```php -'controllerMap' => [ - // ... - 'migrate' => [ - 'class' => 'Yiisoft\Yii\Console\Controllers\MigrateController', - 'migrationPath' => null, - 'migrationNamespaces' => [ - // ... - 'Yiisoft\Yii\Queue\Drivers\Db\migrations', - ], - ], -], -``` - -Then issue the `migrate/up` command: - -```sh -yii migrate/up -``` - -Console -------- - -Console commands are used to execute and manage queued jobs. - -```sh -yii queue/listen [timeout] -``` - -The `listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. The `timeout` parameter specifies the number of seconds to sleep between -querying the queue. This method is most efficient when the command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -The `run` command obtains and executes tasks in a loop until the queue is empty. This works well with -[cron](worker.md#cron). - -The `run` and `listen` commands have options: - -- `--verbose`, `-v`: print execution statuses to console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: enable highlighting for verbose mode. - -```sh -yii queue/info -``` - -The `info` command prints out information about the queue status. - -```sh -yii queue/clear -``` - -The `clear` command clears the queue. - -```sh -yii queue/remove [id] -``` - -The `remove` command removes a job from the queue. diff --git a/docs/guide/driver-file.md b/docs/guide/driver-file.md deleted file mode 100644 index b4fd8d14..00000000 --- a/docs/guide/driver-file.md +++ /dev/null @@ -1,65 +0,0 @@ -File Driver -=========== - -The file driver uses files to store queue data. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\file\Queue::class, - 'path' => '@runtime/queue', - ], - ], -]; -``` - -Console -------- - -Console commands are used to execute and manage queued jobs. - -```sh -yii queue/listen [timeout] -``` - -The `listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. The `timeout` parameter specifies the number of seconds to sleep between -querying the queue. This method is most efficient when the command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -The `run` command obtains and executes tasks in a loop until the queue is empty. This works well with -[cron](worker.md#cron). - -The `run` and `listen` commands have options: - -- `--verbose`, `-v`: print execution statuses to console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: enable highlighting for verbose mode. - -```sh -yii queue/info -``` - -The `info` command prints out information about the queue status. - -```sh -yii queue/clear -``` - -The `clear` command clears the queue. - -```sh -yii queue/remove [id] -``` - -The `remove` command removes a job from the queue. diff --git a/docs/guide/driver-gearman.md b/docs/guide/driver-gearman.md deleted file mode 100644 index 7eb8876c..00000000 --- a/docs/guide/driver-gearman.md +++ /dev/null @@ -1,48 +0,0 @@ -Gearman Driver -============== - -This driver works with Gearman queues. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\gearman\Queue::class, - 'host' => 'localhost', - 'port' => 4730, - 'channel' => 'my_queue', - ], - ], -]; -``` - -Console -------- - -Console commands are used to process queued tasks. - -```sh -yii queue/listen -``` - -`listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. This method is most efficient when command is properly -daemonized via [supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -`run` command obtains and executes tasks in a loop until queue is empty. Works well with -[cron](worker.md#cron). - -`run` and `listen` commands have options: - -- `--verbose`, `-v`: print executing statuses into console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: highlighting for verbose mode. diff --git a/docs/guide/driver-redis.md b/docs/guide/driver-redis.md deleted file mode 100644 index 68cbaa4b..00000000 --- a/docs/guide/driver-redis.md +++ /dev/null @@ -1,76 +0,0 @@ -Redis Driver -============ - -This driver uses Redis to store queue data. - -You have to add the `yiisoft/yii2-redis` extension to your application in order to use it. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'redis' => [ - 'class' => \yii\redis\Connection::class, - // ... - - // retry connecting after connection has timed out - // yiisoft/yii2-redis >=2.0.7 is required for this. - 'retries' => 1, - ], - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'redis' => 'redis', // Redis connection component or its config - 'channel' => 'queue', // Queue channel key - ], - ], -]; -``` - -Console -------- - -Console commands are used to execute and manage queued jobs. - -```sh -yii queue/listen [timeout] -``` - -The `listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. The `timeout` parameter specifies the number of seconds to sleep between -querying the queue. This method is most efficient when the command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -The `run` command obtains and executes tasks in a loop until the queue is empty. This works well with -[cron](worker.md#cron). - -The `run` and `listen` commands have options: - -- `--verbose`, `-v`: print execution statuses to console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: enable highlighting for verbose mode. - -```sh -yii queue/info -``` - -The `info` command prints out information about the queue status. - -```sh -yii queue/clear -``` - -The `clear` command clears the queue. - -```sh -yii queue/remove [id] -``` - -The `remove` command removes a job from the queue. diff --git a/docs/guide/driver-sqs.md b/docs/guide/driver-sqs.md deleted file mode 100644 index fa9d0e4b..00000000 --- a/docs/guide/driver-sqs.md +++ /dev/null @@ -1,62 +0,0 @@ -AWS SQS Driver -============ - -The driver uses AWS SQS to store queue data. - -You have to add `aws/aws-sdk-php` extension to your application in order to use it. - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue', // The component registers own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\sqs\Queue::class, - 'url' => '', - 'key' => '', - 'secret' => '', - 'region' => '', - ], - ], -]; -``` - -Console -------- - -Console command is used to execute tasks. - -```sh -yii queue/listen [timeout] -``` - -`listen` command launches a daemon which infinitely queries the queue. If there are new tasks -they're immediately obtained and executed. `timeout` parameter is number of seconds to wait a job. -It uses SQS "Long Polling" feature, that holds a connection between client and a queue. - -**Important:** `timeout` parameter for SQS driver must be in range between 0 and 20 seconds. - -This method is most efficient when command is properly daemonized via -[supervisor](worker.md#supervisor) or [systemd](worker.md#systemd). - -```sh -yii queue/run -``` - -`run` command obtains and executes tasks in a loop until queue is empty. Works well with -[cron](worker.md#cron). - -`run` and `listen` commands have options: - -- `--verbose`, `-v`: print executing statuses into console. -- `--isolate`: each task is executed in a separate child process. -- `--color`: highlighting for verbose mode. - -```sh -yii queue/clear -``` - -`clear` command clears a queue. diff --git a/docs/guide/gii.md b/docs/guide/gii.md deleted file mode 100644 index fd55930c..00000000 --- a/docs/guide/gii.md +++ /dev/null @@ -1,28 +0,0 @@ -Gii Code generator -================== - -You can use the Gii code generator to create a job template. - -Configuration -------------- - -To use the Gii job generator you have to configure it like the following: - -```php -if (!YII_ENV_TEST) { - $config['bootstrap'][] = 'gii'; - $config['modules']['gii'] = [ - 'class' => 'Yiisoft\Yii\Gii\Module', - 'generators' => [ - 'job' => [ - 'class' => \Yiisoft\Yii\Queue\Gii\Generator::class, - ], - ], - ]; -} - -``` - -After doing so you'll find the generator in the Gii menu. - -![default](https://user-images.githubusercontent.com/1656851/29426628-e9a3e5ae-838f-11e7-859f-6f3cb8649f02.png) diff --git a/docs/guide/usage.md b/docs/guide/usage.md index bccb1000..222ef711 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -5,24 +5,26 @@ Usage basics Configuration ------------- -In order to use the extension you have to configure it like the following: +In order to use the extension you can configure it with DI container like the following: ```php -return [ - 'bootstrap' => [ - 'queue', // The component registers its own console commands - ], - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class, - // Other driver options - ], - ], -]; +$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$logger = $DIcontainer->get(\Psr\Log\LoggerInterface::class); + +$worker = $DIcontainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); +$loop = $DIcontainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); +$driver = $DIcontainer->get(\Yiisoft\Yii\Queue\Driver\DriverInterface::class); + +$queue = new Queue( + $driver, + $eventDisptacher, + $worker, + $loop, + $logger +); ``` -A list of available drivers and their docs is available in the [table of contents](README.md). +Documentation for drivers([synchronous driver](driver-sync.md), AMQP driver), loops, workers Usage @@ -32,36 +34,57 @@ Each task which is sent to the queue should be defined as a separate class. For example, if you need to download and save a file the class may look like the following: ```php -class DownloadJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface +class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface { public $url; public $file; - public function execute($queue) + public function __construct(string $url, string $file) + { + $this->url = $url; + $this->file = $file; + } + + public function getName(): string + { + return 'earlyDefinedQueueHandlerName'; + } + + public function getData() { file_put_contents($this->file, file_get_contents($this->url)); } + + public function getMeta(): array + { + return []; + } } ``` Here's how to send a task to the queue: ```php -Yii::$app->queue->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); +$queue->push( + new DownloadJob('http://example.com/image.jpg', '/tmp/image.jpg') +); ``` To push a job into the queue that should run after 5 minutes: ```php -Yii::$app->queue->delay(5 * 60)->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); +$queue->push( + new class('http://example.com/image.jpg', '/tmp/image.jpg') extends DownloadJob + implements \Yiisoft\Yii\Queue\Payload\DelayablePayloadInterface { + + public function getDelay(): int + { + return 5 * 60; + } + } +); ``` -**Important:** Not all drivers support delayed running. +**Important:** Not all drivers(i.e. synchronous driver) support delayed running. Queue handling @@ -75,82 +98,36 @@ driver documentation. Job status ---------- -The component can track the status of a job that was pushed into the queue. - ```php // Push a job into the queue and get a message ID. -$id = Yii::$app->queue->push(new SomeJob()); +$id = $queue->push(new SomeJob()); + +//Get status of job +$status = $queue->status($id); // Check whether the job is waiting for execution. -Yii::$app->queue->isWaiting($id); +$status->isWaiting(); // Check whether a worker got the job from the queue and executes it. -Yii::$app->queue->isReserved($id); +$status->isReserved($id); // Check whether a worker has executed the job. -Yii::$app->queue->isDone($id); -``` - -**Important:** The RabbitMQ and AWS SQS drivers don't support job statuses. - - -Messaging third party workers ------------------------------ - -You may pass any data to the queue: - -```php -Yii::$app->queue->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); +$status->isDone($id); ``` -This is useful if the queue is processed using a custom third party worker. - -If the worker is not implemented in PHP you have to change the way data is serialized. -For example to serialize to JSON: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` Handling events --------------- The queue triggers the following events: -| Event name | Event class | Triggered | -|------------------------------|-------------|-----------------------------------------------------------| -| Queue::EVENT_BEFORE_PUSH | PushEvent | before adding a job to queue using `Queue::push()` method | -| Queue::EVENT_AFTER_PUSH | PushEvent | after adding a job to queue using `Queue::push()` method | -| Queue::EVENT_BEFORE_EXEC | ExecEvent | before executing a job | -| Queue::EVENT_AFTER_EXEC | ExecEvent | after successful job execution | -| Queue::EVENT_AFTER_ERROR | ExecEvent | on uncaught exception during the job execution | -| cli\Queue:EVENT_WORKER_START | WorkerEvent | when worker has been started | -| cli\Queue:EVENT_WORKER_LOOP | WorkerEvent | on each iteration between requests to queue | -| cli\Queue:EVENT_WORKER_STOP | WorkerEvent | when worker has been stopped | - -You can easily attach your own handler to any of these events. -For example, let's delay the job, if its execution failed with a special exception: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function ($event) { - if ($event->error instanceof TemporaryUnprocessableJobException) { - $queue = $event->sender; - $queue->delay(7200)->push($event->job); - } -}); -``` +| Event class | Triggered | +|--------------------|-----------------------------------------------------------| +| BeforePush | before adding a job to queue using `Queue::push()` method | +| AfterPush | after adding a job to queue using `Queue::push()` method | +| BeforeExecution | before executing a job | +| AfterExecution | after successful job execution | +| JobFailure | on uncaught exception during the job execution | Logging events -------------- @@ -171,49 +148,6 @@ return [ ]; ``` - -Multiple queues ---------------- - -Configuration example: - -```php -return [ - 'bootstrap' => [ - 'queue1', // First component registers its own console commands - 'queue2', // Second component registers its own console commands - ], - 'components' => [ - 'queue1' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - ], - 'queue2' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Db\Queue::class, - 'strictJobType' => false, - 'serializer' => \Yiisoft\Yii\Queue\Serializers\JsonSerializer::class, - ], - ], -]; -``` - -Usage example: - -```php -// Sending a task to the queue to be processed via standard worker -Yii::$app->queue1->push(new DownloadJob([ - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -])); - -// Sending a task to another queue to be processed by a third party worker -Yii::$app->queue2->push([ - 'function' => 'download', - 'url' => 'http://example.com/image.jpg', - 'file' => '/tmp/image.jpg', -]); -``` - - Limitations ----------- From caa0350959ef58af4c1b28c59dd8e4abce46ec66 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Sat, 19 Sep 2020 15:35:56 +0300 Subject: [PATCH 04/12] Update documentation --- README.md | 4 +- docs/guide/README.md | 4 +- docs/guide/driver-sync.md | 24 +++++---- docs/guide/loops.md | 0 docs/guide/retryable.md | 110 +++----------------------------------- docs/guide/usage.md | 57 +++----------------- docs/guide/worker.md | 29 +++------- 7 files changed, 44 insertions(+), 184 deletions(-) create mode 100644 docs/guide/loops.md diff --git a/README.md b/README.md index f4305706..ff00dd86 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,9 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface public function getData() { - file_put_contents($this->file, file_get_contents($this->url)); + return function() { + file_put_contents($this->file, file_get_contents($this->url)); + }; } public function getMeta(): array diff --git a/docs/guide/README.md b/docs/guide/README.md index 19df674c..45820259 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -8,9 +8,11 @@ Introduction * [Usage basics](usage.md) * [Errors and retryable jobs](retryable.md) -* [Starting workers](worker.md) +* [Workers](worker.md) +* [Loops]() Queue Drivers ------------- * [Synchronous](driver-sync.md) +* [AMPQ](https://github.com/yiisoft/yii-queue-amqp) diff --git a/docs/guide/driver-sync.md b/docs/guide/driver-sync.md index 3112883a..e0a1e0a8 100644 --- a/docs/guide/driver-sync.md +++ b/docs/guide/driver-sync.md @@ -1,18 +1,24 @@ Synchronous Driver ================== -Runs tasks synchronously in the same process if the `handle` property is turned on. +Runs tasks synchronously in the same process. It could be used when developing and debugging an application. Configuration example: ```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\Drivers\Sync\Queue::class, - 'handle' => false, // whether tasks should be executed immediately - ], - ], -]; +$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$logger = $DIcontainer->get(\Psr\Log\LoggerInterface::class); + +$worker = $DIcontainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); +$loop = $DIcontainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); +$driver = new Yiisoft\Yii\Queue\Driver\SynchronousDriver($loop, $worker); + +$queue = new Yiisoft\Yii\Queue\Queue( + $driver, + $eventDisptacher, + $worker, + $loop, + $logger +); ``` diff --git a/docs/guide/loops.md b/docs/guide/loops.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/guide/retryable.md b/docs/guide/retryable.md index 3d7c8b9e..8e43159b 100644 --- a/docs/guide/retryable.md +++ b/docs/guide/retryable.md @@ -6,120 +6,26 @@ poorly written code which should be fixed first. But they can also fail due to e problems like a service or a resource being unavailable. This can lead to exceptions or timeouts. -In the latter cases, it's good to be able to retry a job after some time. There are several ways to do this. - -> **Note:** The `ttr` feature described below requires the -> [PHP Process Control (pcntl) extension](http://php.net/manual/en/book.pcntl.php) to be installed -> and the worker command has to use the `--isolate` option (which is enabled by default). - -Retry options -------------- - -The first method is to use queue component options: - -```php -'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\\Queue::class, - 'ttr' => 5 * 60, // Max time for job execution - 'attempts' => 3, // Max number of attempts - ], -], -``` - -The `ttr` (Time to reserve, TTR) option defines the number of seconds during which a job must -be successfully completed. So two things can happen to make a job fail: - - 1. The job throws an exception before `ttr` is over - 2. It would take longer than `ttr` to complete the job (timeout) and thus the - job execution is stopped by the worker. - -In both cases, the job will be sent back to the queue for a retry. Note though, -that in the first case the `ttr` is still "used up" even if the job stops right -after it has stared. I.e. the remaining seconds of `ttr` have to pass before the -job is sent back to the queue. - -The `attempts` option sets the max. number of attempts. If this number is -reached, and the job still isn't done, it will be removed from the queue as completed. - -These options apply to all jobs in the queue. If you need to change this behavior for specific -jobs, see the following method. - -RetryableJobInterface +AttemptsRestrictedPayloadInterface --------------------- -To have more control over the retry logic a job can implement the `RetryableJobInterface`. -For example: - ```php -class SomeJob extends BaseObject implements RetryableJobInterface +class RetryablePayload extends SimplePayload implements AttemptsRestrictedPayloadInterface { - public function execute($queue) - { - //... - } - - public function getTtr() + public function getAttempts(): int { - return 15 * 60; + return 2; } - public function canRetry($attempt, $error) + public function getName(): string { - return ($attempt < 5) && ($error instanceof TemporaryException); + return 'retryable'; } } ``` -The `getTtr()` and `canRetry()` methods have a higher priority than the component options mentioned above. - -Event handlers --------------- - -The third method to control TTR and number of retries for failed jobs involves the -`Queue::EVENT_BEFORE_PUSH` and `Queue::EVENT_AFTER_ERROR` events. - -The TTR can be set with the `Queue::EVENT_BEFORE_PUSH` event: - -```php -Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) { - if ($event->job instanceof SomeJob) { - $event->ttr = 300; - } -}); -``` - -And the `Queue::EVENT_AFTER_ERROR` event can be used to decide whether to try another attempt: - -```php -Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) { - if ($event->job instanceof SomeJob) { - $event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException); - } -}); -``` - -Event handlers are executed after the `RetryableJobInterface` methods, and therefore have the highest -priority. - Restrictions ------------ -Full support for retryable jobs is implemented in the [Beanstalk], [DB], [File], [AMQP Interop] and [Redis] drivers. -The [Sync] driver will not retry failed jobs. The [Gearman] driver doesn't support retryable jobs. -[RabbitMQ] has only its basic retryable support, where the number of attempts can not be set. - -[AWS SQS] uses [Dead Letter Queue] for handling messages that were failed to process. -All unprocessed messages after a maximum number of attempts are moved to that queue. -You should set an address of a Dead Letter Queue and a maximum number of attempts in the AWS Console while creating a queue. - -[Beanstalk]: driver-beanstalk.md -[DB]: driver-db.md -[File]: driver-file.md -[Redis]: driver-redis.md -[Sync]: driver-sync.md -[Gearman]: driver-gearman.md -[RabbitMQ]: driver-amqp.md -[AMQP Interop]: driver-amqp-interop.md -[AWS SQS]: driver-sqs.md -[Dead Letter Queue]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html +Full support for retryable payload is implemented in the [AMQP Interop](https://github.com/yiisoft/yii-queue-amqp) driver. +The [Sync](driver-sync.md) driver will not retry failed jobs diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 222ef711..eede2497 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -24,7 +24,8 @@ $queue = new Queue( ); ``` -Documentation for drivers([synchronous driver](driver-sync.md), AMQP driver), loops, workers +Documentation for drivers([synchronous driver](driver-sync.md), [AMQP driver](https://github.com/yiisoft/yii-queue-amqp)), +[loops](loops.md), [workers](worker.md) Usage @@ -52,7 +53,9 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface public function getData() { - file_put_contents($this->file, file_get_contents($this->url)); + return function () { + file_put_contents($this->file, file_get_contents($this->url)); + }; } public function getMeta(): array @@ -132,21 +135,8 @@ The queue triggers the following events: Logging events -------------- -The component provides the `LogBehavior` to log Queue events using -[Yii's built-in Logger](http://www.yiiframework.com/doc-2.0/guide-runtime-logging.html). - -To enable it, simply configure the queue component as follows: - -```php -return [ - 'components' => [ - 'queue' => [ - 'class' => \Yiisoft\Yii\Queue\redis\Queue::class, - 'as log' => \Yiisoft\Yii\Queue\LogBehavior::class - ], - ], -]; -``` +In order to log events, please refer to documentation of implementation of EventDispatcherInterface +(i.e. [Yii Event Dispatcher](https://github.com/yiisoft/event-dispatcher#events-hierarchy)) Limitations ----------- @@ -155,35 +145,4 @@ When using queues it's important to remember that tasks are put into and obtaine processes. Therefore avoid external dependencies when executing a task if you're not sure if they are available in the environment where the worker does its job. -All the data to process the task should be put into properties of your job object and be sent into the queue along with it. - -If you need to process an `ActiveRecord` then send its ID instead of the object itself. When processing you have to extract -it from DB. - -For example: - -```php -Yii::$app->queue->push(new SomeJob([ - 'userId' => Yii::$app->user->id, - 'bookId' => $book->id, - 'someUrl' => Url::to(['controller/action']), -])); -``` - -Task class: - -```php -class SomeJob extends BaseObject implements \Yiisoft\Yii\Queue\JobInterface -{ - public $userId; - public $bookId; - public $someUrl; - - public function execute($queue) - { - $user = User::findOne($this->userId); - $book = Book::findOne($this->bookId); - //... - } -} -``` +All the data to process the task should be provided with data of your payload diff --git a/docs/guide/worker.md b/docs/guide/worker.md index 99caa1a0..b1f5e89a 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -1,3 +1,7 @@ +Configuration +================ + + Starting Workers ================ @@ -33,17 +37,8 @@ to the specified log file. For more info about Supervisor's configuration and usage see its [documentation](http://supervisord.org). -Note that worker daemons started with `queue/listen` are only supported by the [File], [Db], [Redis], -[RabbitMQ], [AMQP Interop], [Beanstalk], [Gearman] and [AWS SQS] drivers. For additional options see driver guide. - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[AMQP Interop]: driver-amqp-interop.md -[RabbitMQ]: driver-amqp.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md -[AWS SQS]: driver-sqs.md +Note that worker daemons started with `queue/listen` are only supported by the +[AMQP Interop](https://github.com/yiisoft/yii-queue-amqp) driver. For additional options see driver guide. Systemd ------- @@ -109,14 +104,4 @@ Config example: * * * * * /usr/bin/php /var/www/my_project/yii queue/run ``` -In this case cron will run the command every minute. - -The `queue/run` command is supported by the [File], [Db], [Redis], [Beanstalk], [Gearman], [AWS SQS] drivers. -For additional options see driver guide. - -[File]: driver-file.md -[Db]: driver-db.md -[Redis]: driver-redis.md -[Beanstalk]: driver-beanstalk.md -[Gearman]: driver-gearman.md -[AWS SQS]: driver-sqs.md \ No newline at end of file +In this case cron will run the command every minute. \ No newline at end of file From cf6a7f9adafa9bfdbeeaf3c6bd8fa380d37467c7 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Tue, 22 Sep 2020 13:41:54 +0300 Subject: [PATCH 05/12] Add worker configuration --- docs/guide/README.md | 1 - docs/guide/usage.md | 2 +- docs/guide/worker.md | 12 +++++++++++- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/guide/README.md b/docs/guide/README.md index 45820259..933b3657 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -9,7 +9,6 @@ Introduction * [Usage basics](usage.md) * [Errors and retryable jobs](retryable.md) * [Workers](worker.md) -* [Loops]() Queue Drivers ------------- diff --git a/docs/guide/usage.md b/docs/guide/usage.md index eede2497..cde91b39 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -25,7 +25,7 @@ $queue = new Queue( ``` Documentation for drivers([synchronous driver](driver-sync.md), [AMQP driver](https://github.com/yiisoft/yii-queue-amqp)), -[loops](loops.md), [workers](worker.md) +[workers](worker.md) Usage diff --git a/docs/guide/worker.md b/docs/guide/worker.md index b1f5e89a..f9439944 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -1,6 +1,16 @@ Configuration ================ - +```php +$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$handlers = []; +$worker = new Worker( + $handlers, + $eventDisptacher, + new \Psr\Log\NullLogger(), + new \Yiisoft\Injector\Injector($DIcontainer), + $DIcontainer +); +``` Starting Workers ================ From 330d9d78e1ceb41985227d950181ef115b0080b7 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Tue, 22 Sep 2020 14:37:11 +0300 Subject: [PATCH 06/12] Add handler example --- docs/guide/worker.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/guide/worker.md b/docs/guide/worker.md index f9439944..53393d5b 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -2,7 +2,10 @@ Configuration ================ ```php $eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); -$handlers = []; +$handlers = [ + 'simple' => fn() => 'someWork', + 'anotherHandler' => [QueueHandlerCollection::class, 'methodName'] +]; $worker = new Worker( $handlers, $eventDisptacher, From 336b3061bb8b32ee3c773f8d354cf15d18bd5a79 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Tue, 22 Sep 2020 14:49:27 +0300 Subject: [PATCH 07/12] Fix sentence --- docs/guide/usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/usage.md b/docs/guide/usage.md index cde91b39..5bf47f8d 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -87,7 +87,7 @@ $queue->push( ); ``` -**Important:** Not all drivers(i.e. synchronous driver) support delayed running. +**Important:** Not every driver (such as synchronous driver) supports delayed execution. Queue handling From fb8a4904f12497e2829c82f1745b69ecf02c433f Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Tue, 22 Sep 2020 16:32:38 +0300 Subject: [PATCH 08/12] Docs fixes --- docs/guide/README.md | 2 +- docs/guide/driver-sync.md | 8 ++++---- docs/guide/usage.md | 10 +++++----- docs/guide/worker.md | 6 +++--- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guide/README.md b/docs/guide/README.md index 933b3657..b35ea324 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -14,4 +14,4 @@ Queue Drivers ------------- * [Synchronous](driver-sync.md) -* [AMPQ](https://github.com/yiisoft/yii-queue-amqp) +* [AMQP](https://github.com/yiisoft/yii-queue-amqp) diff --git a/docs/guide/driver-sync.md b/docs/guide/driver-sync.md index e0a1e0a8..b64d3419 100644 --- a/docs/guide/driver-sync.md +++ b/docs/guide/driver-sync.md @@ -7,11 +7,11 @@ It could be used when developing and debugging an application. Configuration example: ```php -$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); -$logger = $DIcontainer->get(\Psr\Log\LoggerInterface::class); +$eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$logger = $DIContainer->get(\Psr\Log\LoggerInterface::class); -$worker = $DIcontainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); -$loop = $DIcontainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); +$worker = $DIContainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); +$loop = $DIContainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); $driver = new Yiisoft\Yii\Queue\Driver\SynchronousDriver($loop, $worker); $queue = new Yiisoft\Yii\Queue\Queue( diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 5bf47f8d..123021c8 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -8,12 +8,12 @@ Configuration In order to use the extension you can configure it with DI container like the following: ```php -$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); -$logger = $DIcontainer->get(\Psr\Log\LoggerInterface::class); +$eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$logger = $DIContainer->get(\Psr\Log\LoggerInterface::class); -$worker = $DIcontainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); -$loop = $DIcontainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); -$driver = $DIcontainer->get(\Yiisoft\Yii\Queue\Driver\DriverInterface::class); +$worker = $DIContainer->get(\Yiisoft\Yii\Queue\Worker\WorkerInterface::class); +$loop = $DIContainer->get(\Yiisoft\Yii\Queue\Cli\LoopInterface::class); +$driver = $DIContainer->get(\Yiisoft\Yii\Queue\Driver\DriverInterface::class); $queue = new Queue( $driver, diff --git a/docs/guide/worker.md b/docs/guide/worker.md index 53393d5b..e51af094 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -1,7 +1,7 @@ Configuration ================ ```php -$eventDisptacher = $DIcontainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); +$eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); $handlers = [ 'simple' => fn() => 'someWork', 'anotherHandler' => [QueueHandlerCollection::class, 'methodName'] @@ -10,8 +10,8 @@ $worker = new Worker( $handlers, $eventDisptacher, new \Psr\Log\NullLogger(), - new \Yiisoft\Injector\Injector($DIcontainer), - $DIcontainer + new \Yiisoft\Injector\Injector($DIContainer), + $DIContainer ); ``` From a67b7619344b162fefe71de87f17a6c2112ee5a8 Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Wed, 23 Sep 2020 15:01:09 +0300 Subject: [PATCH 09/12] Docs fixes --- README.md | 20 ++++++++------------ docs/guide/retryable.md | 2 +- docs/guide/usage.md | 27 ++++++++++++++------------- docs/guide/worker.md | 3 --- 4 files changed, 23 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 14a3bee8..03d3666d 100644 --- a/README.md +++ b/README.md @@ -44,13 +44,13 @@ For example, if you need to download and save a file the class may look like the ```php class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface { - public $url; - public $file; + public string $url; + public string $filePath; - public function __construct(string $url, string $file) + public function __construct(string $url, string $filePath) { $this->url = $url; - $this->file = $file; + $this->filePath = $filePath; } public function getName(): string @@ -60,14 +60,10 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface public function getData() { - return function() { - file_put_contents($this->file, file_get_contents($this->url)); - }; - } - - public function getMeta(): array - { - return []; + return [ + 'destinationFile' => $this->filePath, + 'url' => $this->url + ]; } public function getMeta(): array diff --git a/docs/guide/retryable.md b/docs/guide/retryable.md index 8e43159b..ca10d5e6 100644 --- a/docs/guide/retryable.md +++ b/docs/guide/retryable.md @@ -27,5 +27,5 @@ class RetryablePayload extends SimplePayload implements AttemptsRestrictedPayloa Restrictions ------------ -Full support for retryable payload is implemented in the [AMQP Interop](https://github.com/yiisoft/yii-queue-amqp) driver. +Full support for retryable payload is implemented in the [AMQP](https://github.com/yiisoft/yii-queue-amqp) driver. The [Sync](driver-sync.md) driver will not retry failed jobs diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 123021c8..32573ec8 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -5,7 +5,7 @@ Usage basics Configuration ------------- -In order to use the extension you can configure it with DI container like the following: +In order to use the extension you can configure it with a DI container in the following way: ```php $eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); @@ -24,8 +24,8 @@ $queue = new Queue( ); ``` -Documentation for drivers([synchronous driver](driver-sync.md), [AMQP driver](https://github.com/yiisoft/yii-queue-amqp)), -[workers](worker.md) +See also the documentation for concrete drivers ([synchronous driver](driver-sync.md), +[AMQP driver](https://github.com/yiisoft/yii-queue-amqp)) and [workers](worker.md) Usage @@ -37,13 +37,13 @@ For example, if you need to download and save a file the class may look like the ```php class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface { - public $url; - public $file; + public string $url; + public string $filePath; - public function __construct(string $url, string $file) + public function __construct(string $url, string $filePath) { $this->url = $url; - $this->file = $file; + $this->filePath = $filePath; } public function getName(): string @@ -53,9 +53,10 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface public function getData() { - return function () { - file_put_contents($this->file, file_get_contents($this->url)); - }; + return [ + 'destinationFile' => $this->filePath, + 'url' => $this->url + ]; } public function getMeta(): array @@ -105,7 +106,7 @@ Job status // Push a job into the queue and get a message ID. $id = $queue->push(new SomeJob()); -//Get status of job +//Get job status $status = $queue->status($id); // Check whether the job is waiting for execution. @@ -135,7 +136,7 @@ The queue triggers the following events: Logging events -------------- -In order to log events, please refer to documentation of implementation of EventDispatcherInterface +In order to log events, please refer to EventDispatcherInterface implementation documentation (i.e. [Yii Event Dispatcher](https://github.com/yiisoft/event-dispatcher#events-hierarchy)) Limitations @@ -145,4 +146,4 @@ When using queues it's important to remember that tasks are put into and obtaine processes. Therefore avoid external dependencies when executing a task if you're not sure if they are available in the environment where the worker does its job. -All the data to process the task should be provided with data of your payload +All the data to process the task should be provided with your payload `getData()` method. diff --git a/docs/guide/worker.md b/docs/guide/worker.md index e51af094..592a93fc 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -50,9 +50,6 @@ to the specified log file. For more info about Supervisor's configuration and usage see its [documentation](http://supervisord.org). -Note that worker daemons started with `queue/listen` are only supported by the -[AMQP Interop](https://github.com/yiisoft/yii-queue-amqp) driver. For additional options see driver guide. - Systemd ------- From 111a0b96a44da30e08c5bbfc240e75d264d5a2db Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Wed, 23 Sep 2020 15:54:54 +0300 Subject: [PATCH 10/12] Fix naming --- docs/guide/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/README.md b/docs/guide/README.md index b35ea324..abed6c5b 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,4 +1,4 @@ -Yii3 Queue extension +Yii Queue extension ==================== An extension for running tasks asynchronously via queues. From 0ee80eeac1a0b2e41e551e12d3b8a0f2de5d09b0 Mon Sep 17 00:00:00 2001 From: viktorprogger Date: Mon, 28 Sep 2020 12:41:40 +0300 Subject: [PATCH 11/12] A bit about message handlers --- README.md | 63 +++++++++++++++++++++++++++++++++++++------- docs/guide/worker.md | 22 +++++++++++++++- 2 files changed, 74 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 03d3666d..cee272cd 100644 --- a/README.md +++ b/README.md @@ -33,35 +33,40 @@ or add "yiisoft/yii-queue": "~3.0" ``` -to the require section of your `composer.json` file. +to the `require` section of your `composer.json` file. Basic Usage ----------- -Each task which is sent to queue should be defined as a separate class. -For example, if you need to download and save a file the class may look like the following: +Each queue task consists of two parts: +1. Data payload. It is a class implementing `PayloadInterface`. +1. Payload handler. It is a callable called by a `WorkerInterface` which handles every queue message. + +For example, if you need to download and save a file, the payload may look like the following: ```php class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface { + public const NAME = 'file-download'; + public string $url; - public string $filePath; + public string $fileName; - public function __construct(string $url, string $filePath) + public function __construct(string $url, string $fileName) { $this->url = $url; - $this->filePath = $filePath; + $this->fileName = $fileName; } public function getName(): string { - return 'earlyDefinedQueueHandlerName'; + return self::NAME; } - public function getData() + public function getData(): array { return [ - 'destinationFile' => $this->filePath, + 'destinationFile' => $this->fileName, 'url' => $this->url ]; } @@ -73,13 +78,51 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface } ``` +And it's handler may look like this: + +```php +class FileDownloader +{ + private string $absolutePath; + + public function __construct(string $absolutePath) + { + $this->absolutePath = $absolutePath; + } + + public function handle(\Yiisoft\Yii\Queue\Message\MessageInterface $downloadMessage): void + { + $fileName = $downloadMessage->getPayloadData()['destinationFile']; + $path = "$this->absolutePath/$fileName"; + file_put_contents($path, file_get_contents($downloadMessage->getPayloadData()['url'])); + } +} +``` + +The last thing we should do is to create configuration for the `Yiisoft\Yii\Queue\Worker\Worker`: +```php +$handlers = [DownloadJob::NAME => [new FileDownloader('/path/to/save/files'), 'handle']]; +$worker = new \Yiisoft\Yii\Queue\Worker\Worker( + $handlers, // Here it is + $dispatcher, + $logger, + $injector, + $container +); +``` + Here's how to send a task into the queue: ```php $queue->push( - new DownloadJob('http://example.com/image.jpg', '/tmp/image.jpg') + new DownloadJob('http://example.com/image.jpg', 'new-image-name.jpg') ); ``` + + + + + To push a job into the queue that should run after 5 minutes: ```php diff --git a/docs/guide/worker.md b/docs/guide/worker.md index 592a93fc..30d459ea 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -1,5 +1,25 @@ Configuration ================ + +In order to use implemented worker, you should resolve it's dependencies (e.g. through DI container) +and define handlers for each message which will be consumed by this worker; + +Handlers are callables indexed by payload names. When a message will be consumed from the queue, a callable associated with it's payload name will be called. + +#### Handler format +Handler can be any callable with a couple of additions: + +- If handler is given as an array of two strings, it will be treated a DI container service id and its method. +E.g. `[ClassName::class, 'handle']` will be resolved to `$container->get(ClassName::class)->handle()`. + +- The second important thing to know is that an `Injector` is used to call the handlers. +This means you can define handlers as closures with their own dependenies which will be resolved with DI container. +In the example below you can see a closure in which `message` will be taken from the queue +and `ClientInterface` will be resolved via DI container. +```php +'payloadName' => fn (MessageInterface $message, ClientInterface $client) => $client->send($message->getPayloadData()), +``` + ```php $eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); $handlers = [ @@ -114,4 +134,4 @@ Config example: * * * * * /usr/bin/php /var/www/my_project/yii queue/run ``` -In this case cron will run the command every minute. \ No newline at end of file +In this case cron will run the command every minute. From 2f2047148ead9214299f568cf3f62d1ff8e562fe Mon Sep 17 00:00:00 2001 From: Anton Samoylenko Date: Tue, 29 Sep 2020 10:14:05 +0300 Subject: [PATCH 12/12] Update documentation --- README.md | 4 ++-- docs/guide/usage.md | 2 +- docs/guide/worker.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cee272cd..683353c9 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Basic Usage Each queue task consists of two parts: 1. Data payload. It is a class implementing `PayloadInterface`. -1. Payload handler. It is a callable called by a `WorkerInterface` which handles every queue message. +2. Payload handler. It is a callable called by a `WorkerInterface` which handles every queue message. For example, if you need to download and save a file, the payload may look like the following: @@ -78,7 +78,7 @@ class DownloadJob implements Yiisoft\Yii\Queue\Payload\PayloadInterface } ``` -And it's handler may look like this: +And its handler may look like the following: ```php class FileDownloader diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 32573ec8..8538628c 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -5,7 +5,7 @@ Usage basics Configuration ------------- -In order to use the extension you can configure it with a DI container in the following way: +You can configure it with a DI container in the following way: ```php $eventDisptacher = $DIContainer->get(\Psr\EventDispatcher\EventDispatcherInterface::class); diff --git a/docs/guide/worker.md b/docs/guide/worker.md index 30d459ea..f51eb144 100644 --- a/docs/guide/worker.md +++ b/docs/guide/worker.md @@ -1,10 +1,10 @@ Configuration ================ -In order to use implemented worker, you should resolve it's dependencies (e.g. through DI container) +In order to use implemented worker, you should resolve its dependencies (e.g. through DI container) and define handlers for each message which will be consumed by this worker; -Handlers are callables indexed by payload names. When a message will be consumed from the queue, a callable associated with it's payload name will be called. +Handlers are callables indexed by payload names. When a message is consumed from the queue, a callable associated with its payload name is called. #### Handler format Handler can be any callable with a couple of additions: