[!!!][TASK] Use Priority enum in Incident class

Related: #2
jobrouter · Dec 14, 2022 · f1f7725 · f1f7725
1 parent 17f32d7
commit f1f7725
Show file tree

Hide file tree

Showing 12 changed files with 106 additions and 87 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,9 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+- Incident class accepts as a priority only a Priority enum
+
 ### Removed
 - Compatibility with PHP < 8.1
 - Compatibility with JobRouter® < 2022.1

diff --git a/docs/api/incident.rst b/docs/api/incident.rst
@@ -10,18 +10,6 @@ Model\\Incident
 
    Incident model class which collects the fields for a process instance start.
 
-   .. php:const:: const PRIORITY_HIGH = 3
-
-      The value of the high priority.
-
-   .. php:const:: const PRIORITY_LOW = 1
-
-      The value of the low priority.
-
-   .. php:const:: const PRIORITY_NORMAL = 2
-
-      The value of the default priority.
-
    .. php:method:: addRowToSubTable($subTableName, $row)
 
       Add a row to a sub table.
@@ -56,9 +44,9 @@ Model\\Incident
 
    .. php:method:: getPriority()
 
-      Retrieve the priority, or :php:`null` if not defined.
+      Retrieve the priority, see :ref:`api-priority`.
 
-      :returns ?int: The priority.
+      :returns \\Brotkrueml\\JobRouterClient\\Enumerations\\Priority: The priority.
 
    .. php:method:: getProcessTableField($name)
 
@@ -134,10 +122,9 @@ Model\\Incident
 
    .. php:method:: setPriority($priority)
 
-      Sets the priority (values 1-3 are allowed, you can use the PRIORITY
-      constants defined in this class).
+      Sets the priority, see :ref:`api-priority`
 
-      :param int $priority: The priority.
+      :param \\Brotkrueml\\JobRouterClient\\Enumerations\\Priority $priority: The priority.
       :returns self: An instance of itself.
 
    .. php:method:: setProcessTableField($name, $value)

diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -35,3 +35,9 @@ API
    incident
    file
    filestorage
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Enumerations
+
+   priority
diff --git a/docs/api/priority.rst b/docs/api/priority.rst
@@ -0,0 +1,23 @@
+.. include:: /_includes.rst.txt
+
+.. _api-priority:
+
+======================
+Enumerations\\Priority
+======================
+
+.. php:class:: enum Brotkrueml\JobRouterClient\Enumerations\Priority
+
+   Priority enumeration to be used in :ref:`Incident class <api-incident>`.
+
+   .. php:const:: case PRIORITY_HIGH = 3
+
+      The value of the high priority.
+
+   .. php:const:: case PRIORITY_LOW = 1
+
+      The value of the low priority.
+
+   .. php:const:: case PRIORITY_NORMAL = 2
+
+      The value of the default priority.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -11,6 +11,12 @@ to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 `Unreleased <https://github.com/brotkrueml/jobrouter-client/compare/v1.4.0...HEAD>`_
 ----------------------------------------------------------------------------------------
 
+Changed
+^^^^^^^
+
+
+* Incident class accepts as a priority only a Priority enum
+
 Removed
 ^^^^^^^
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -21,6 +21,7 @@ license <https://creativecommons.org/licenses/by-nc-sa/4.0/>`_.
    installation
    usage
    api/index
+   upgrade
    changelog
 
 .. toctree::

diff --git a/docs/upgrade.rst b/docs/upgrade.rst
@@ -0,0 +1,26 @@
+.. include:: /_includes.rst.txt
+
+.. _upgrade:
+
+=======
+Upgrade
+=======
+
+From version 1.x to 2.0
+=======================
+
+With JobRouter Client 2.0 the minimum requirements have changed, supported are
+now:
+
+-  PHP ≥ 8.1
+-  JobRouter® ≥ 2022.1
+
+API changes
+-----------
+
+-  :ref:`Incident <api-incident>` class:
+
+   -  The :php:`->setPriority()` method accepts only a :ref:`Priority
+      <api-priority>` enum, previously it was an integer or null.
+   -  The :php:`->getPriority()` method returns a :ref:`Priority
+      <api-priority>` enum, previously it was an integer or null.
diff --git a/src/Client/IncidentsClientDecorator.php b/src/Client/IncidentsClientDecorator.php
@@ -14,6 +14,7 @@
 
 namespace Brotkrueml\JobRouterClient\Client;
 
+use Brotkrueml\JobRouterClient\Enumerations\Priority;
 use Brotkrueml\JobRouterClient\Exception\HttpException;
 use Brotkrueml\JobRouterClient\Model\Incident;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
@@ -66,8 +67,8 @@ private function buildMultipart(Incident $incident): array
             $multipart['summary'] = $incident->getSummary();
         }
 
-        if (\is_int($incident->getPriority())) {
-            $multipart['priority'] = (string)$incident->getPriority();
+        if ($incident->getPriority() !== Priority::Normal) {
+            $multipart['priority'] = (string)$incident->getPriority()->value;
         }
 
         if (\is_int($incident->getPool())) {

diff --git a/src/Enumerations/Priority.php b/src/Enumerations/Priority.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the JobRouter Client.
+ * https://github.com/brotkrueml/jobrouter-client
+ *
+ * Copyright (c) 2019-2022 Chris Müller
+ *
+ * For the full copyright and license information, please view the
+ * LICENSE.txt file that was distributed with this source code.
+ */
+
+namespace Brotkrueml\JobRouterClient\Enumerations;
+
+enum Priority: int
+{
+    case Low = 1;
+    case Normal = 2;
+    case High = 3;
+}
diff --git a/src/Model/Incident.php b/src/Model/Incident.php
@@ -14,14 +14,11 @@
 
 namespace Brotkrueml\JobRouterClient\Model;
 
+use Brotkrueml\JobRouterClient\Enumerations\Priority;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
 
 final class Incident
 {
-    public const PRIORITY_LOW = 1;
-    public const PRIORITY_NORMAL = 2;
-    public const PRIORITY_HIGH = 3;
-
     /**
      * @var positive-int|null
      */
@@ -30,10 +27,7 @@ final class Incident
     private string $username = '';
     private string $jobFunction = '';
     private string $summary = '';
-    /**
-     * @var int<1,3>|null
-     */
-    private ?int $priority = null;
+    private Priority $priority = Priority::Normal;
     /**
      * @var positive-int|null
      */
@@ -113,27 +107,13 @@ public function setSummary(string $summary): self
         return $this;
     }
 
-    public function getPriority(): ?int
+    public function getPriority(): Priority
     {
         return $this->priority;
     }
 
-    /**
-     * @param int<1,3> $priority
-     * @throws \InvalidArgumentException
-     */
-    public function setPriority(int $priority): self
+    public function setPriority(Priority $priority): self
     {
-        if ($priority < self::PRIORITY_LOW || $priority > self::PRIORITY_HIGH) { // @phpstan-ignore-line
-            throw new \InvalidArgumentException(
-                \sprintf(
-                    'proprity has to be an integer between 1 and 3, "%d" given',
-                    $priority
-                ),
-                1578225130
-            );
-        }
-
         $this->priority = $priority;
 
         return $this;

diff --git a/tests/Unit/Client/IncidentsClientDecoratorTest.php b/tests/Unit/Client/IncidentsClientDecoratorTest.php
@@ -16,6 +16,7 @@
 
 use Brotkrueml\JobRouterClient\Client\ClientInterface;
 use Brotkrueml\JobRouterClient\Client\IncidentsClientDecorator;
+use Brotkrueml\JobRouterClient\Enumerations\Priority;
 use Brotkrueml\JobRouterClient\Model\Incident;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -111,9 +112,9 @@ public function dataProvider(): iterable
         ];
 
         yield 'Given priority' => [
-            (new Incident())->setPriority(2),
+            (new Incident())->setPriority(Priority::High),
             [
-                'priority' => '2',
+                'priority' => '3',
             ],
         ];
 

diff --git a/tests/Unit/Model/IncidentTest.php b/tests/Unit/Model/IncidentTest.php
@@ -14,6 +14,7 @@
 
 namespace Brotkrueml\JobRouterClient\Tests\Unit\Model;
 
+use Brotkrueml\JobRouterClient\Enumerations\Priority;
 use Brotkrueml\JobRouterClient\Model\Incident;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
 use PHPUnit\Framework\TestCase;
@@ -70,9 +71,9 @@ public function summaryIsAnEmptyStringWhenNotSet(): void
     /**
      * @test
      */
-    public function priorityIsNullWhenNotSet(): void
+    public function priorityIsNormalWhenNotExplicitlySet(): void
     {
-        self::assertNull($this->subject->getPriority());
+        self::assertSame(Priority::Normal, $this->subject->getPriority());
     }
 
     /**
@@ -183,48 +184,10 @@ public function setAndGetSummaryAreCorrectImplemented(): void
      */
     public function setAndGetPriorityAreCorrectImplemented(): void
     {
-        $actual = $this->subject->setPriority(2);
+        $actual = $this->subject->setPriority(Priority::High);
 
         self::assertSame($this->subject, $actual);
-        self::assertSame(2, $this->subject->getPriority());
-    }
-
-    /**
-     * @test
-     */
-    public function setPriorityAcceptsOnlyAllowedRange(): void
-    {
-        $exception = null;
-        try {
-            $this->subject->setPriority(1);
-            $this->subject->setPriority(2);
-            $this->subject->setPriority(3);
-        } catch (\InvalidArgumentException $exception) {
-        }
-
-        self::assertNull($exception, 'Unexpected InvalidArgumentException');
-    }
-
-    /**
-     * @test
-     */
-    public function setPriorityThrowsExceptionWhenTooLow(): void
-    {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionCode(1578225130);
-
-        $this->subject->setPriority(0);
-    }
-
-    /**
-     * @test
-     */
-    public function setPriorityThrowsExceptionWhenTooHigh(): void
-    {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionCode(1578225130);
-
-        $this->subject->setPriority(4);
+        self::assertSame(Priority::High, $this->subject->getPriority());
     }
 
     /**