Merge pull request #2586 from flow-php/types-structure-compatibility

Types structure compatibility

Author: norberttech

documentation/upgrading.md

@@ -152,6 +152,21 @@ flow_telemetry:
         - 'cache.http_client.pool'
 ```
 
+### 9) `flow-php/types` - a `Type` implementation's generic parameter is the value it represents
+
+| Before                           | After                                    |
+|----------------------------------|------------------------------------------|
+| `ListType<string>`               | `ListType<list<string>>`                 |
+| `MapType<string, int>`           | `MapType<array<string, int>>`            |
+| `StructureType<mixed>`           | `StructureType<array<array-key, mixed>>` |
+| `ClassStringType<Foo>`           | `ClassStringType<class-string<Foo>>`     |
+| `ListType::element(): Type<T>`   | `Type<value-of<T>>`                      |
+| `MapType::key(): Type<TKey>`     | `Type<key-of<T>>`                        |
+| `MapType::value(): Type<TValue>` | `Type<value-of<T>>`                      |
+| `type_string(): Type`            | `type_string(): StringType`              |
+
+Update `ListType`, `MapType`, `StructureType` and `ClassStringType` parameters in your own docblocks.
+
 ---
 
 ## Upgrading from 0.41.x to 0.42.x

src/adapter/etl-adapter-json/src/Flow/ETL/Adapter/JSON/SchemaConverter.php

@@ -1020,7 +1020,7 @@ private function typeToJsonSchema(Type $type): array
     }
 
     /**
-     * @param MapType<array-key, mixed> $type
+     * @param MapType<array<array-key, mixed>> $type
      *
      * @return array<string, mixed>
      */
@@ -1041,7 +1041,7 @@ private function mapToJsonSchema(MapType $type): array
     }
 
     /**
-     * @param StructureType<mixed> $type
+     * @param StructureType<array<array-key, mixed>> $type
      *
      * @return array<string, mixed>
      */

src/adapter/etl-adapter-parquet/src/Flow/ETL/Adapter/Parquet/SchemaConverter.php

@@ -96,6 +96,13 @@ public function toParquet(Schema $schema): ParquetSchema
      */
     private function flowToParquet(string $name, Type $type, bool $nullable): Column
     {
+        if ($type instanceof StructureType && count($type->optionalElements())) {
+            throw new RuntimeException(sprintf(
+                'Parquet schema does not support structure optional elements, given: %s',
+                $type->toString(),
+            ));
+        }
+
         $repetition = $nullable ? ParquetSchema\Repetition::OPTIONAL : ParquetSchema\Repetition::REQUIRED;
 
         return match ($type::class) {

src/adapter/etl-adapter-parquet/tests/Flow/ETL/Adapter/Parquet/Tests/Unit/FlowToParquetSchemaTest.php

@@ -5,6 +5,7 @@
 namespace Flow\ETL\Adapter\Parquet\Tests\Unit;
 
 use Flow\ETL\Adapter\Parquet\SchemaConverter;
+use Flow\ETL\Exception\RuntimeException;
 use Flow\ETL\Tests\FlowTestCase;
 use Flow\Parquet\ParquetFile\Schema as ParquetSchema;
 use Flow\Parquet\ParquetFile\Schema\FlatColumn;
@@ -82,4 +83,28 @@ public function test_convert_etl_entries_to_parquet_fields(): void
             )),
         );
     }
+
+    public function test_converting_structure_with_optional_elements_throws(): void
+    {
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            'Parquet schema does not support structure optional elements, given: structure{a: string, b?: string}',
+        );
+
+        (new SchemaConverter())->toParquet(schema(structure_schema('structure', type_structure(['a' => type_string()], [
+            'b' => type_string(),
+        ]))));
+    }
+
+    public function test_converting_nested_structure_with_optional_elements_throws(): void
+    {
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            'Parquet schema does not support structure optional elements, given: structure{b: string, c?: string}',
+        );
+
+        (new SchemaConverter())->toParquet(schema(structure_schema('structure', type_structure([
+            'a' => type_structure(['b' => type_string()], ['c' => type_string()]),
+        ]))));
+    }
 }

src/adapter/etl-adapter-seal/src/Flow/ETL/Adapter/Seal/SchemaConverter.php

@@ -102,6 +102,13 @@ private function flag(Metadata $metadata, SealMetadata $key, bool $default): boo
      */
     private function flowToSealField(string $name, Type $type, bool $multiple, Metadata $metadata): AbstractField
     {
+        if ($type instanceof StructureType && count($type->optionalElements())) {
+            throw new RuntimeException(sprintf(
+                'Seal schema does not support structure optional elements, given: %s',
+                $type->toString(),
+            ));
+        }
+
         return match ($type::class) {
             EnumType::class,
             HTMLElementType::class,

src/adapter/etl-adapter-seal/tests/Flow/ETL/Adapter/Seal/Tests/Unit/SchemaConverterTest.php

@@ -101,6 +101,22 @@ public function test_throws_when_no_identifier_is_provided(): void
         to_seal_schema(schema(str_schema('name')), 'index');
     }
 
+    public function test_throws_when_structure_has_optional_elements(): void
+    {
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            'Seal schema does not support structure optional elements, given: structure{name: string, nickname?: string}',
+        );
+
+        to_seal_schema(
+            schema(
+                str_schema('id'),
+                structure_schema('author', type_structure(['name' => type_string()], ['nickname' => type_string()])),
+            ),
+            'index',
+        );
+    }
+
     public function test_using_metadata_to_override_default_field_flags(): void
     {
         $sealSchema = to_seal_schema(

src/adapter/etl-adapter-xml/src/Flow/ETL/Adapter/XML/XMLEncoder.php

@@ -105,6 +105,13 @@ public function encode(array $batch): array
      */
     private function normalize(string $name, Type $type, mixed $value): XMLNode|XMLAttribute
     {
+        if ($type instanceof StructureType && count($type->optionalElements())) {
+            throw new RuntimeException(sprintf(
+                'XML encoder does not support structure optional elements, given: %s',
+                $type->toString(),
+            ));
+        }
+
         if (str_starts_with($name, $this->attributePrefix)) {
             return new XMLAttribute(substr($name, strlen($this->attributePrefix)), type_string()->cast($value));
         }

src/adapter/etl-adapter-xml/tests/Flow/ETL/Adapter/XML/Tests/Unit/XMLEncoderTest.php

@@ -8,6 +8,7 @@
 use DateTimeImmutable;
 use Flow\ETL\Adapter\XML\XMLEncoder;
 use Flow\ETL\Adapter\XML\XMLWriter\DOMDocumentWriter;
+use Flow\ETL\Exception\RuntimeException;
 use Flow\ETL\Row\TypedRowValues;
 use Flow\ETL\Tests\Fixtures\Enum\BackedIntEnum;
 use Flow\ETL\Tests\FlowTestCase;
@@ -156,6 +157,20 @@ public function test_encodes_structure_into_nested_nodes(): void
         );
     }
 
+    public function test_encoding_structure_with_optional_elements_throws(): void
+    {
+        $encoder = new XMLEncoder(new DOMDocumentWriter());
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            'XML encoder does not support structure optional elements, given: structure{city: string, zip?: string}',
+        );
+
+        $encoder->encode([new TypedRowValues(['address' => ['city' => 'Krakow']], ['address' => type_structure([
+            'city' => type_string(),
+        ], ['zip' => type_string()])])]);
+    }
+
     public function test_encodes_null_scalar_as_an_empty_node(): void
     {
         $encoder = new XMLEncoder(new DOMDocumentWriter());

src/bridge/monolog/http/tests/Flow/Bridge/Monolog/Http/Tests/Unit/Config/RequestConfigTest.php

@@ -48,7 +48,7 @@ public function test_constructor_throws_exception_when_mask_sanitizer_has_invali
     {
         $this->expectException(InvalidTypeException::class);
         $this->expectExceptionMessage(
-            'Expected type "structure{type: \'mask\', character?: string, offset?: integer}", got "map<string, string>"',
+            'Expected type "structure{type: \'mask\', character?: string, offset?: integer}", got "structure{type: string, character: string, offset: string}"',
         );
 
         new RequestConfig(sanitizers: [

src/bridge/monolog/http/tests/Flow/Bridge/Monolog/Http/Tests/Unit/Config/ResponseConfigTest.php

@@ -48,7 +48,7 @@ public function test_constructor_throws_exception_when_mask_sanitizer_has_invali
     {
         $this->expectException(InvalidTypeException::class);
         $this->expectExceptionMessage(
-            'Expected type "structure{type: \'mask\', character?: string, offset?: integer}", got "map<string, string>"',
+            'Expected type "structure{type: \'mask\', character?: string, offset?: integer}", got "structure{type: string, character: string, offset: string}"',
         );
 
         new ResponseConfig(sanitizers: [