Add Array.php usage example and update Composer script to include it

Author: georgedeploy

src/Abstract/AbstractTypeInterface.php

@@ -34,7 +34,7 @@ interface AbstractTypeInterface
      */
     public static function fromString(string $value): static;
 
-    //    public static function tryFromMixed(mixed $value): static|Undefined;
+    //        public static function tryFromMixed(mixed $value): static|Undefined;  //todo enable it
 
     /**
      * Returns a normalized string representation of the underlying value.

src/Abstract/Array/ArrayType.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract\Array;
+
+use IteratorAggregate;
+use JsonSerializable;
+use PhpTypedValues\Abstract\AbstractType;
+
+/**
+ * Base implementation for array typed values.
+ *
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ *
+ * @psalm-immutable
+ */
+abstract readonly class ArrayType implements ArrayTypeInterface, IteratorAggregate, JsonSerializable
+{
+}

src/Abstract/Array/ArrayTypeInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Abstract\Array;
+
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+/**
+ * Contract for array typed values.
+ *
+ * @psalm-immutable
+ */
+interface ArrayTypeInterface
+{
+    public function value(): array;
+
+    public static function fromArray(array $value): static;
+
+    public static function tryFromArray(array $value): static|Undefined;
+
+}

src/Usage/Composite/Composite.php

@@ -32,3 +32,5 @@
 echo $test->getId()->toString() . PHP_EOL;
 echo $test->getFirstName()->toString() . PHP_EOL;
 echo $test->getHeight()->toString() . PHP_EOL;
+
+echo json_encode($test, JSON_THROW_ON_ERROR) . PHP_EOL;

src/Usage/Example/ArrayOfStrings.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Usage\Example;
+
+require_once 'vendor/autoload.php';
+
+use PhpTypedValues\Abstract\Array\ArrayType;
+use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\String\StringNonEmpty;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+/**
+ * @internal
+ *
+ * @psalm-internal PhpTypedValues
+ * @psalm-immutable
+ */
+final readonly class ArrayOfStrings extends ArrayType
+{
+    /**
+     * @param StringNonEmpty[] $value
+     *
+     * @throws StringTypeException
+     * @throws TypeException
+     */
+    public function __construct(
+        private array $value,
+    ) {
+        if ($value === []) {
+            throw new TypeException('Expected non-empty array');
+        }
+
+        foreach ($value as $item) {
+            if (!$item instanceof StringNonEmpty) {
+                throw new StringTypeException('Expected array of StringNonEmpty instance');
+            }
+        }
+    }
+
+    /**
+     * @throws StringTypeException
+     * @throws TypeException
+     */
+    public static function fromArray(array $value): self
+    {
+        $typed = [];
+        foreach ($value as $item) {
+            $typed[] = StringNonEmpty::fromString($item);
+        }
+
+        return new self($typed);
+    }
+
+    /**
+     * @return StringNonEmpty[]
+     */
+    public function value(): array
+    {
+        return $this->value;
+    }
+
+    /**
+     * @return non-empty-list<non-empty-string>
+     */
+    public function toStrings(): array
+    {
+        $result = [];
+        foreach ($this->value as $item) {
+            /** @var non-empty-string $value */
+            $value = $item->toString();
+            $result[] = $value;
+        }
+
+        /** @var non-empty-list<non-empty-string> $result */
+        return $result;
+    }
+
+    /** @return non-empty-list<non-empty-string> */
+    public function jsonSerialize(): array
+    {
+        return $this->toStrings();
+    }
+
+    /**
+     * @return Traversable<StringNonEmpty>
+     */
+    public function getIterator(): Traversable
+    {
+        yield from $this->value;
+    }
+
+    public static function tryFromArray(array $value): static|Undefined
+    {
+        $typed = [];
+        foreach ($value as $item) {
+            $typed[] = StringNonEmpty::tryFromString($item);
+        }
+
+        return new self($typed);
+    }
+}

src/Usage/Example/EarlyFail.php

@@ -17,6 +17,7 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ * @psalm-immutable
  */
 final readonly class EarlyFail
 {

src/Usage/Example/LateFail.php

@@ -16,6 +16,7 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ * @psalm-immutable
  */
 final readonly class LateFail
 {

src/Usage/Example/OptionalFail.php

@@ -4,8 +4,10 @@
 
 namespace PhpTypedValues\Usage\Example;
 
+use JsonSerializable;
 use PhpTypedValues\Exception\FloatTypeException;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\UndefinedTypeException;
 use PhpTypedValues\Float\FloatPositive;
 use PhpTypedValues\Integer\IntegerPositive;
 use PhpTypedValues\String\StringNonEmpty;
@@ -17,8 +19,9 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ * @psalm-immutable
  */
-final readonly class OptionalFail
+final readonly class OptionalFail implements JsonSerializable
 {
     public function __construct(
         private IntegerPositive $id,
@@ -59,4 +62,16 @@ public function getFirstName(): StringNonEmpty|Undefined
     {
         return $this->firstName;
     }
+
+    /**
+     * @throws UndefinedTypeException
+     */
+    public function jsonSerialize(): array
+    {
+        return [
+            'id' => $this->id->toString(),
+            'firstName' => $this->firstName->toString(),
+            'height' => $this->height->toString(),
+        ];
+    }
 }