ErrorEvent mark as deprecated

zhuravljov · zhuravljov · commit d291834dc3df · 2018-09-20T01:22:55.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ Yii2 Queue Extension Change Log
 - Bug #269: Handling of broken messages that are not unserialized correctly (zhuravljov)
 - Bug #267: Fixed symfony/process incompatibility (rob006)
 - Enh: Job execution result that forwarded to the event handler (zhuravljov)
+- Enh: ErrorEvent mark as deprecated (zhuravljov)
 
 2.1.0 May 24, 2018
 ------------------
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -4,6 +4,12 @@ Upgrading Instructions
 This file contains the upgrade notes. These notes highlight changes that could break your
 application when you upgrade the package from one version to another.
 
+Upgrade to 2.1.1
+----------------
+
+* `\yii\queue\ErrorEvent` has been deprecated and will be removed in `3.0`.
+  Use `\yii\queue\ExecEvent` instead.
+
 Upgrade from 2.0.1 to 2.0.2
 ---------------------------
 
diff --git a/docs/guide-ja/retryable.md b/docs/guide-ja/retryable.md
@@ -92,7 +92,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {
 そして `Queue::EVENT_AFTER_ERROR` イベントを使って、もう一度試行するかどうかを決定することが出来ます。
 
 ```php
-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {
+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);
     }
diff --git a/docs/guide-ja/usage.md b/docs/guide-ja/usage.md
@@ -135,7 +135,7 @@ return [
 | Queue::EVENT_AFTER_PUSH      | PushEvent   | `Queue::push()` メソッドを使ってジョブをキューに追加した後 |
 | Queue::EVENT_BEFORE_EXEC     | ExecEvent   | ジョブを実行する前 |
 | Queue::EVENT_AFTER_EXEC      | ExecEvent   | ジョブが完了した後 |
-| Queue::EVENT_AFTER_ERROR     | ErrorEvent  | ジョブ実行中にキャッチされない例外が発生したとき |
+| Queue::EVENT_AFTER_ERROR     | ExecEvent   | ジョブ実行中にキャッチされない例外が発生したとき |
 | cli\Queue:EVENT_WORKER_START | WorkerEvent | ワーカが開始されたとき |
 | cli\Queue:EVENT_WORKER_LOOP  | WorkerEvent | キューに対するリクエストを繰り返すたびに |
 | cli\Queue:EVENT_WORKER_STOP  | WorkerEvent | ワーカが停止されたとき |
diff --git a/docs/guide-ru/retryable.md b/docs/guide-ru/retryable.md
@@ -84,7 +84,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {
 А событие `Queue::EVENT_AFTER_ERROR` — чтобы определить задание на повторную попытку:
 
 ```php
-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {
+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);
     }
diff --git a/docs/guide-ru/usage.md b/docs/guide-ru/usage.md
@@ -137,7 +137,7 @@ return [
 | Queue::EVENT_AFTER_PUSH      | PushEvent     | Добавление задания в очередь используя метод `Queue::push()`  |
 | Queue::EVENT_BEFORE_EXEC     | ExecEvent     | Перед каждым выполнением задания                              |
 | Queue::EVENT_AFTER_EXEC      | ExecEvent     | После каждого успешного выполнения задания                    |
-| Queue::EVENT_AFTER_ERROR     | ErrorEvent    | Если при выполнение задания случилось непойманное исключение  |
+| Queue::EVENT_AFTER_ERROR     | ExecEvent     | Если при выполнение задания случилось непойманное исключение  |
 | cli\Queue:EVENT_WORKER_START | WorkerEvent   | В момент запуска нового воркера                               |
 | cli\Queue:EVENT_WORKER_LOOP  | WorkerEvent   | В цикле между опросами очереди                                |
 | cli\Queue:EVENT_WORKER_STOP  | WorkerEvent   | В момент остановки воркера                                    |
diff --git a/docs/guide-zh-CN/retryable.md b/docs/guide-zh-CN/retryable.md
@@ -73,7 +73,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {
 并且 `Queue::EVENT_AFTER_ERROR` 事件可用于设置新的尝试:
 
 ```php
-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {
+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);
     }
diff --git a/docs/guide-zh-CN/usage.md b/docs/guide-zh-CN/usage.md
@@ -133,7 +133,7 @@ return [
 | 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     | ErrorEvent  | When uncaught exception occurred during the 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                              |
diff --git a/docs/guide/retryable.md b/docs/guide/retryable.md
@@ -92,7 +92,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {
 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 (ErrorEvent $event) {
+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);
     }
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
@@ -135,7 +135,7 @@ The queue triggers the following events:
 | 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     | ErrorEvent  | on uncaught exception during the 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                              |
diff --git a/src/ErrorEvent.php b/src/ErrorEvent.php
@@ -10,16 +10,10 @@
 /**
  * Error Event.
  *
+ * @deprecated Will be removed in 3.0. Use ExecEvent instead.
+ *
  * @author Roman Zhuravlev <zhuravljov@gmail.com>
  */
 class ErrorEvent extends ExecEvent
 {
-    /**
-     * @var \Exception|\Throwable
-     */
-    public $error;
-    /**
-     * @var bool
-     */
-    public $retry;
 }
diff --git a/src/ExecEvent.php b/src/ExecEvent.php
@@ -15,12 +15,28 @@
 class ExecEvent extends JobEvent
 {
     /**
-     * @var int attempt number
+     * @var int attempt number.
+     * @see Queue::EVENT_BEFORE_EXEC
+     * @see Queue::EVENT_AFTER_EXEC
+     * @see Queue::EVENT_AFTER_ERROR
      */
     public $attempt;
     /**
-     * @var mixed result of a job execution
+     * @var mixed result of a job execution in case job is done.
+     * @see Queue::EVENT_AFTER_EXEC
      * @since 2.1.1
      */
     public $result;
+    /**
+     * @var null|\Exception|\Throwable
+     * @see Queue::EVENT_AFTER_ERROR
+     * @since 2.1.1
+     */
+    public $error;
+    /**
+     * @var null|bool
+     * @see Queue::EVENT_AFTER_ERROR
+     * @since 2.1.1
+     */
+    public $retry;
 }
diff --git a/src/InvalidJobException.php b/src/InvalidJobException.php
@@ -10,7 +10,7 @@
 use Throwable;
 
 /**
- * Invalid Job Exception
+ * Invalid Job Exception.
  *
  * Throws when serialized message cannot be unserialized to a job.
  *
diff --git a/src/JobEvent.php b/src/JobEvent.php
@@ -14,7 +14,7 @@
  *
  * @author Roman Zhuravlev <zhuravljov@gmail.com>
  */
-class JobEvent extends Event
+abstract class JobEvent extends Event
 {
     /**
      * @var Queue
diff --git a/src/LogBehavior.php b/src/LogBehavior.php
@@ -76,9 +76,9 @@ public function afterExec(ExecEvent $event)
     }
 
     /**
-     * @param ErrorEvent $event
+     * @param ExecEvent $event
      */
-    public function afterError(ErrorEvent $event)
+    public function afterError(ExecEvent $event)
     {
         $title = $this->getExecTitle($event);
         Yii::endProfile($title, Queue::class);
diff --git a/src/Queue.php b/src/Queue.php
@@ -194,36 +194,35 @@ public function getWorkerPid()
     protected function handleMessage($id, $message, $ttr, $attempt)
     {
         list($job, $error) = $this->unserializeMessage($message);
-
         $event = new ExecEvent([
             'id' => $id,
             'job' => $job,
             'ttr' => $ttr,
             'attempt' => $attempt,
+            'error' => $error,
         ]);
         $this->trigger(self::EVENT_BEFORE_EXEC, $event);
         if ($event->handled) {
             return true;
         }
-
-        if ($error) {
-            return $this->handleError($event->id, $event->job, $event->ttr, $event->attempt, $error);
+        if ($event->error) {
+            return $this->handleError($event);
         }
-
         try {
             $event->result = $event->job->execute($this);
         } catch (\Exception $error) {
-            return $this->handleError($event->id, $event->job, $event->ttr, $event->attempt, $error);
+            $event->error = $error;
+            return $this->handleError($event);
         } catch (\Throwable $error) {
-            return $this->handleError($event->id, $event->job, $event->ttr, $event->attempt, $error);
+            $event->error = $error;
+            return $this->handleError($event);
         }
         $this->trigger(self::EVENT_AFTER_EXEC, $event);
-
         return true;
     }
 
     /**
-     * Unserializes
+     * Unserializes.
      *
      * @param string $id of the job
      * @param string $serialized message
@@ -248,30 +247,18 @@ public function unserializeMessage($serialized)
     }
 
     /**
-     * @param string|null $id
-     * @param JobInterface $job
-     * @param int $ttr
-     * @param int $attempt
-     * @param \Exception|\Throwable $error
+     * @param ExecEvent $event
      * @return bool
      * @internal
      */
-    public function handleError($id, $job, $ttr, $attempt, $error)
+    public function handleError(ExecEvent $event)
     {
-        $retry = $attempt < $this->attempts;
-        if ($error instanceof InvalidJobException) {
-            $retry = false;
-        } elseif ($job instanceof RetryableJobInterface) {
-            $retry = $job->canRetry($attempt, $error);
+        $event->retry = $event->attempt < $this->attempts;
+        if ($event->error instanceof InvalidJobException) {
+            $event->retry = false;
+        } elseif ($event->job instanceof RetryableJobInterface) {
+            $event->retry = $event->job->canRetry($event->attempt, $event->error);
         }
-        $event = new ErrorEvent([
-            'id' => $id,
-            'job' => $job,
-            'ttr' => $ttr,
-            'attempt' => $attempt,
-            'error' => $error,
-            'retry' => $retry,
-        ]);
         $this->trigger(self::EVENT_AFTER_ERROR, $event);
         return !$event->retry;
     }
diff --git a/src/cli/Command.php b/src/cli/Command.php
@@ -11,6 +11,7 @@
 use Symfony\Component\Process\Exception\RuntimeException as ProcessRuntimeException;
 use Symfony\Component\Process\Process;
 use yii\console\Controller;
+use yii\queue\ExecEvent;
 
 /**
  * Base Command.
@@ -196,7 +197,13 @@ protected function handleMessage($id, $message, $ttr, $attempt)
             return $result === self::EXEC_DONE;
         } catch (ProcessRuntimeException $error) {
             list($job) = $this->queue->unserializeMessage($message);
-            return $this->queue->handleError($id, $job, $ttr, $attempt, $error);
+            return $this->queue->handleError(new ExecEvent([
+                'id' => $id,
+                'job' => $job,
+                'ttr' => $ttr,
+                'attempt' => $attempt,
+                'error' => $error,
+            ]));
         }
     }
 }
diff --git a/src/cli/VerboseBehavior.php b/src/cli/VerboseBehavior.php
@@ -10,7 +10,6 @@
 use yii\base\Behavior;
 use yii\console\Controller;
 use yii\helpers\Console;
-use yii\queue\ErrorEvent;
 use yii\queue\ExecEvent;
 use yii\queue\JobInterface;
 
@@ -82,9 +81,9 @@ public function afterExec(ExecEvent $event)
     }
 
     /**
-     * @param ErrorEvent $event
+     * @param ExecEvent $event
      */
-    public function afterError(ErrorEvent $event)
+    public function afterError(ExecEvent $event)
     {
         $this->command->stdout(date('Y-m-d H:i:s'), Console::FG_YELLOW);
         $this->command->stdout($this->jobTitle($event), Console::FG_GREY);
diff --git a/tests/JobEventTest.php b/tests/JobEventTest.php
@@ -8,7 +8,6 @@
 namespace tests;
 
 use yii\queue\closure\Behavior as ClosureBehavior;
-use yii\queue\ErrorEvent;
 use yii\queue\ExecEvent;
 use yii\queue\InvalidJobException;
 use yii\queue\JobEvent;
@@ -31,7 +30,7 @@ public function testInvalidJob()
         $queue = new SyncQueue(['strictJobType' => false]);
         $queue->on(Queue::EVENT_BEFORE_EXEC, $eventHandler);
         $queue->on(Queue::EVENT_AFTER_ERROR, $eventHandler);
-        $queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {
+        $queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) {
             $this->assertTrue($event->error instanceof InvalidJobException);
             $this->assertFalse($event->retry);
         });

Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {`
`92`	`92`	そして `Queue::EVENT_AFTER_ERROR` イベントを使って、もう一度試行するかどうかを決定することが出来ます。
`93`	`93`
`94`	`94`	```php
`95`		`-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {`
	`95`	`+Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) {`
`96`	`96`	`if ($event->job instanceof SomeJob) {`
`97`	`97`	`$event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException);`
`98`	`98`	`}`
Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {`
`84`	`84`	А событие `Queue::EVENT_AFTER_ERROR` — чтобы определить задание на повторную попытку:
`85`	`85`
`86`	`86`	```php
`87`		`-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {`
	`87`	`+Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) {`
`88`	`88`	`if ($event->job instanceof SomeJob) {`
`89`	`89`	`$event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException);`
`90`	`90`	`}`
Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ Yii::$app->queue->on(Queue::EVENT_BEFORE_PUSH, function (PushEvent $event) {`
`73`	`73`	并且 `Queue::EVENT_AFTER_ERROR` 事件可用于设置新的尝试:
`74`	`74`
`75`	`75`	```php
`76`		`-Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {`
	`76`	`+Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ExecEvent $event) {`
`77`	`77`	`if ($event->job instanceof SomeJob) {`
`78`	`78`	`$event->retry = ($event->attempt < 5) && ($event->error instanceof TemporaryException);`
`79`	`79`	`}`