Enhancement: Implement OptionalValueGenerator

CHANGELOG.md

@@ -11,9 +11,11 @@ For a full diff see [`f4208b3...main`][f4208b3...main].
 ### Added
 
 - Added `ValueGenerator` ([#1]), by [@localheinz]
+- Added `OptionalValueGenerator` ([#2]), by [@localheinz]
 
 [f4208b3...main]: https://github.com/ergebnis/data-generator/compare/f4208b3...main
 
 [#1]: https://github.com/ergebnis/data-generator/pull/1
+[#2]: https://github.com/ergebnis/data-generator/pull/2
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -26,8 +26,36 @@ composer require ergebnis/data-generator
 
 This project comes with the following data generators:
 
+- [`Ergebnis\DataGenerator\OptionalValueGenerator`](#optionalvaluegenerator)
 - [`Ergebnis\DataGenerator\ValueGenerator`](#valuegenerator)
 
+### `OptionalValueGenerator`
+
+#### Generate one or more values from a list of `string` values
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Ergebnis\DataGenerator;
+
+$generator = new DataGenerator\OptionalValueGenerator(
+    'foo',
+    'bar',
+    'baz',
+);
+
+foreach ($generator->generate() as $value) {
+    echo $value . PHP_EOL
+}
+
+// empty string
+// foo
+// bar
+// baz
+```
+
 ### `ValueGenerator`
 
 Use the `ValueGenerator` to generate one or more values from a list of `string` values:

psalm-baseline.xml

@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="5.18.0@b113f3ed0259fd6e212d87c3df80eec95a6abf19">
+  <file src="test/Unit/OptionalValueGeneratorTest.php">
+    <MixedArgument>
+      <code>$values</code>
+    </MixedArgument>
+  </file>
   <file src="test/Unit/ValueGeneratorTest.php">
     <MixedArgument>
       <code>$values</code>

src/OptionalValueGenerator.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2017-2023 Andreas Möller
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE.md file that was distributed with this source code.
+ *
+ * @see https://github.com/ergebnis/data-generator
+ */
+
+namespace Ergebnis\DataGenerator;
+
+final class OptionalValueGenerator implements StringGenerator
+{
+    /**
+     * @var array<string>
+     */
+    private readonly array $values;
+
+    /**
+     * @throws Exception\InvalidValuesException
+     */
+    public function __construct(string ...$values)
+    {
+        if (0 === \count($values)) {
+            throw Exception\InvalidValuesException::empty();
+        }
+
+        $this->values = $values;
+    }
+
+    public function generate(): \Generator
+    {
+        yield '';
+
+        foreach ($this->values as $value) {
+            yield $value;
+        }
+    }
+}

test/Unit/OptionalValueGeneratorTest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2017-2023 Andreas Möller
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE.md file that was distributed with this source code.
+ *
+ * @see https://github.com/ergebnis/data-generator
+ */
+
+use Ergebnis\DataGenerator\Exception;
+use Ergebnis\DataGenerator\OptionalValueGenerator;
+use Ergebnis\DataGenerator\Test;
+use PHPUnit\Framework;
+
+#[Framework\Attributes\CoversClass(OptionalValueGenerator::class)]
+#[Framework\Attributes\UsesClass(Exception\InvalidValuesException::class)]
+final class OptionalValueGeneratorTest extends Framework\TestCase
+{
+    use Test\Util\Helper;
+
+    public function testConstructorRejectsEmptyValues(): void
+    {
+        $this->expectException(Exception\InvalidValuesException::class);
+
+        new OptionalValueGenerator();
+    }
+
+    public function testGenerateReturnsGeneratorThatYieldsValues(): void
+    {
+        $values = self::faker()->words();
+
+        $generator = new OptionalValueGenerator(...$values);
+
+        $generated = \iterator_to_array($generator->generate());
+
+        $expected = \array_merge(
+            [
+                '',
+            ],
+            $values,
+        );
+
+        self::assertSame($expected, $generated);
+    }
+}