Add abbility to getRequiredObject

Author: pionl

docs/content/en/index.md

@@ -368,6 +368,8 @@ $attributes->getString('attributeName');
 
 - Allows getting object of specified type.
 - You can transform raw value to expected object by using transformers (with `GetterTransformer`)
+- Use `getObject` if value is nullable
+- Use `getRequiredObject` to throw missing value exception if value is null (since v0.6.2)
 
 ```php
 use Wrkflow\GetValue\Contracts\GetValueTransformerContract;

src/GetValue.php

@@ -526,6 +526,26 @@ public function getObject(
         return null;
     }
 
+    /**
+     * @template T of object
+     * @param class-string<T>       $expectedClass
+     *
+     * @return T
+     */
+    public function getRequiredObject(
+        string $expectedClass,
+        string|array $key,
+        GetValueTransformerContract $getValueTransformer
+    ): object {
+        $result = $this->getObject($expectedClass, $key, $getValueTransformer);
+
+        if ($result === null) {
+            throw $this->exceptionBuilder->missingValue($this->data->getKey($key));
+        }
+
+        return $result;
+    }
+
     public function makeInstance(AbstractData $data): self
     {
         return new self(

tests/GetValueXMLDataTest.php

@@ -93,8 +93,11 @@ public function testGetXMLGetter(): void
     public function testGetObject(): void
     {
         $result = $this->data->getObject(TestEntity::class, 'object', new TestEntityTransformer());
-        $this->assertNotNull($result);
-        $this->assertEquals('x', $result->type);
+        $this->assertObjectResult($result);
+
+        $result = $this->data->getRequiredObject(TestEntity::class, 'object', new TestEntityTransformer());
+
+        $this->assertObjectResult($result);
     }
 
     public function testGetObjectIncorrectResult(): void
@@ -103,6 +106,12 @@ public function testGetObjectIncorrectResult(): void
         $this->assertNull($result);
     }
 
+    public function testGetRequiredObjectIncorrectResult(): void
+    {
+        $this->expectException(MissingValueForKeyException::class);
+        $this->data->getRequiredObject(TestEntity::class, 'object', new NullTransformer());
+    }
+
     protected function assertObject(GetValue $object): void
     {
         $this->assertEquals('x', $object->getRequiredString('type'));
@@ -113,4 +122,10 @@ protected function assertObject(GetValue $object): void
         $this->assertEquals('test', $child->getRequiredString(self::KeyTitle));
         $this->assertEquals(null, $child->getString('title2'));
     }
+
+    protected function assertObjectResult(mixed $result): void
+    {
+        $this->assertNotNull($result);
+        $this->assertEquals('x', $result->type);
+    }
 }