[!!!][TASK] Provide a step number on instantiation of Incident class

Additionally, the step number cannot be null anymore and must be a positive integer.
Otherwise an exception is thrown.

CHANGELOG.md

@@ -9,6 +9,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 - Incident class accepts as a priority only a Priority enum
+- Incident class must be instantiated with a step number
+- Step number in Incident class must be an integer, null is not allowed anymore
 
 ### Removed
 - Compatibility with PHP < 8.1

docs/api/incident.rst

@@ -10,6 +10,10 @@ Model\\Incident
 
    Incident model class which collects the fields for a process instance start.
 
+   .. php:method:: __construct($step)
+
+      :param int $step: The step number (must be a positive integer).
+
    .. php:method:: addRowToSubTable($subTableName, $row)
 
       Add a row to a sub table.
@@ -66,7 +70,7 @@ Model\\Incident
 
       Retrieve the step number.
 
-      :returns ?int: The step number, or :php:`null` if not defined.
+      :returns int: The step number.
 
    .. php:method:: getStepEscalationDate()
 

docs/changelog.rst

@@ -16,6 +16,8 @@ Changed
 
 
 * Incident class accepts as a priority only a Priority enum
+* Incident class must be instantiated with a step number
+* Step number in Incident class must be an integer, null is not allowed anymore
 
 Removed
 ^^^^^^^

docs/upgrade.rst

@@ -20,6 +20,11 @@ API changes
 
 -  :ref:`Incident <api-incident>` class:
 
+   -  On instantiation the step number must be passed as argument in the
+      constructor.
+   -  The :php:`->setStep()` method accepts only a positive integer, not a null
+      value anymore.
+   -  The :php:`->getStep()` method returns always an integer.
    -  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

src/Exception/InvalidStepNumberException.php

@@ -0,0 +1,29 @@
+<?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\Exception;
+
+final class InvalidStepNumberException extends \DomainException implements ExceptionInterface
+{
+    public static function forStepNumber(int $stepNumber): self
+    {
+        return new self(
+            \sprintf(
+                'The given step number "%d" is invalid, it must be an integer greater than 0',
+                $stepNumber
+            ),
+            1671041151
+        );
+    }
+}

src/Model/Incident.php

@@ -15,14 +15,12 @@
 namespace Brotkrueml\JobRouterClient\Model;
 
 use Brotkrueml\JobRouterClient\Enumerations\Priority;
+use Brotkrueml\JobRouterClient\Exception\InvalidStepNumberException;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
 
 final class Incident
 {
-    /**
-     * @var positive-int|null
-     */
-    private ?int $step = null;
+    private int $step;
     private string $initiator = '';
     private string $username = '';
     private string $jobFunction = '';
@@ -44,16 +42,22 @@ final class Incident
      */
     private array $subTables = [];
 
-    public function getStep(): ?int
+    public function __construct(int $step)
+    {
+        $this->setStep($step);
+    }
+
+    public function getStep(): int
     {
         return $this->step;
     }
 
-    /**
-     * @param positive-int $step
-     */
     public function setStep(int $step): self
     {
+        if ($step <= 0) {
+            throw InvalidStepNumberException::forStepNumber($step);
+        }
+
         $this->step = $step;
 
         return $this;

tests/Unit/Client/IncidentsClientDecoratorTest.php

@@ -77,93 +77,104 @@ public function requestWithIncidentIsProcessedAsMultipartAndPassedToClient(
     public function dataProvider(): iterable
     {
         yield 'Given step' => [
-            (new Incident())->setStep(1),
+            new Incident(42),
             [
-                'step' => '1',
+                'step' => '42',
             ],
         ];
 
         yield 'Given initiator' => [
-            (new Incident())->setInitiator('some initiator'),
+            (new Incident(1))->setInitiator('some initiator'),
             [
+                'step' => '1',
                 'initiator' => 'some initiator',
             ],
         ];
 
         yield 'Given username' => [
-            (new Incident())->setUsername('some username'),
+            (new Incident(1))->setUsername('some username'),
             [
+                'step' => '1',
                 'username' => 'some username',
             ],
         ];
 
         yield 'Given jobfunction' => [
-            (new Incident())->setJobFunction('some jobfunction'),
+            (new Incident(1))->setJobFunction('some jobfunction'),
             [
+                'step' => '1',
                 'jobfunction' => 'some jobfunction',
             ],
         ];
 
         yield 'Given summary' => [
-            (new Incident())->setSummary('some summary'),
+            (new Incident(1))->setSummary('some summary'),
             [
+                'step' => '1',
                 'summary' => 'some summary',
             ],
         ];
 
         yield 'Given priority' => [
-            (new Incident())->setPriority(Priority::High),
+            (new Incident(1))->setPriority(Priority::High),
             [
+                'step' => '1',
                 'priority' => '3',
             ],
         ];
 
         yield 'Given pool' => [
-            (new Incident())->setPool(42),
+            (new Incident(1))->setPool(42),
             [
+                'step' => '1',
                 'pool' => '42',
             ],
         ];
 
         yield 'Given simulation is true' => [
-            (new Incident())->setSimulation(true),
+            (new Incident(1))->setSimulation(true),
             [
+                'step' => '1',
                 'simulation' => '1',
             ],
         ];
 
         yield 'Given simulation is false' => [
-            (new Incident())->setSimulation(false),
-            [],
+            (new Incident(1))->setSimulation(false),
+            [
+                'step' => '1',
+            ],
         ];
 
         yield 'Given step escalation date' => [
-            (new Incident())->setStepEscalationDate(
+            (new Incident(1))->setStepEscalationDate(
                 new \DateTimeImmutable(
                     '2020-01-30 12:34:56',
                     new \DateTimeZone('America/Chicago')
                 )
             ),
             [
+                'step' => '1',
                 'step_escalation_date' => '2020-01-30T12:34:56-06:00',
             ],
         ];
 
         yield 'Given incident escalation date' => [
-            (new Incident())->setIncidentEscalationDate(
+            (new Incident(1))->setIncidentEscalationDate(
                 new \DateTimeImmutable(
                     '2020-01-31 01:23:45',
                     new \DateTimeZone('Europe/Berlin')
                 )
             ),
             [
+                'step' => '1',
                 'incident_escalation_date' => '2020-01-31T01:23:45+01:00',
             ],
         ];
 
         $fileStub = $this->createStub(FileInterface::class);
         yield 'Given process table fields' => [
-            (new Incident())
+            (new Incident(1))
                 ->setProcessTableField('some field', 'some value')
                 ->setProcessTableField('another field', 'another value')
                 ->setProcessTableField('different field', 'different value')
@@ -172,6 +183,7 @@ public function dataProvider(): iterable
                 ->setProcessTableField('boolean false field', false)
                 ->setProcessTableField('file field', $fileStub),
             [
+                'step' => '1',
                 'processtable[fields][0][name]' => 'some field',
                 'processtable[fields][0][value]' => 'some value',
                 'processtable[fields][1][name]' => 'another field',
@@ -190,7 +202,7 @@ public function dataProvider(): iterable
         ];
 
         yield 'Given sub table fields' => [
-            (new Incident())
+            (new Incident(1))
                 ->setRowsForSubTable(
                     'some subtable',
                     [
@@ -216,6 +228,7 @@ public function dataProvider(): iterable
                     ]
                 ),
             [
+                'step' => '1',
                 'subtables[0][name]' => 'some subtable',
                 'subtables[0][rows][0][fields][0][name]' => 'some string',
                 'subtables[0][rows][0][fields][0][value]' => 'some value 1',
@@ -250,7 +263,7 @@ public function requestWithIncidentIsProcessedAndReturnsInstanceOfResponseInterf
             ->method('request')
             ->willReturn($responseStub);
 
-        $actual = $this->subject->request('GET', 'some/route', new Incident());
+        $actual = $this->subject->request('GET', 'some/route', new Incident(1));
 
         self::assertInstanceOf(ResponseInterface::class, $actual);
     }

tests/Unit/Exception/InvalidStepNumberExceptionTest.php

@@ -0,0 +1,32 @@
+<?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\Tests\Unit\Exception;
+
+use Brotkrueml\JobRouterClient\Exception\InvalidStepNumberException;
+use PHPUnit\Framework\TestCase;
+
+final class InvalidStepNumberExceptionTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function forStepNumber(): void
+    {
+        $actual = InvalidStepNumberException::forStepNumber(0);
+
+        self::assertSame('The given step number "0" is invalid, it must be an integer greater than 0', $actual->getMessage());
+        self::assertSame(1671041151, $actual->getCode());
+    }
+}

tests/Unit/Model/IncidentTest.php

@@ -15,6 +15,7 @@
 namespace Brotkrueml\JobRouterClient\Tests\Unit\Model;
 
 use Brotkrueml\JobRouterClient\Enumerations\Priority;
+use Brotkrueml\JobRouterClient\Exception\InvalidStepNumberException;
 use Brotkrueml\JobRouterClient\Model\Incident;
 use Brotkrueml\JobRouterClient\Resource\FileInterface;
 use PHPUnit\Framework\TestCase;
@@ -25,15 +26,26 @@ class IncidentTest extends TestCase
 
     protected function setUp(): void
     {
-        $this->subject = new Incident();
+        $this->subject = new Incident(1);
     }
 
     /**
      * @test
      */
-    public function stepIsNullWhenNotSet(): void
+    public function stepIsCorrectlySetOnInstantiation(): void
     {
-        self::assertNull($this->subject->getStep());
+        self::assertSame(1, $this->subject->getStep());
+    }
+
+    /**
+     * @test
+     */
+    public function exceptionIsThrownOnInstantiationWhenStepNumberIsInvalid(): void
+    {
+        $this->expectException(InvalidStepNumberException::class);
+        $this->expectExceptionMessageMatches('#"0"#');
+
+        new Incident(0);
     }
 
     /**
@@ -135,6 +147,17 @@ public function setAndGetStepAreCorrectImplemented(): void
         self::assertSame(42, $this->subject->getStep());
     }
 
+    /**
+     * @test
+     */
+    public function setStepThrowsExceptionWhenStepNumberIsInvalid(): void
+    {
+        $this->expectException(InvalidStepNumberException::class);
+        $this->expectExceptionMessageMatches('#"0"#');
+
+        $this->subject->setStep(0);
+    }
+
     /**
      * @test
      */