Improve builder specification

Author: nyamsprod

src/InnerList.php

@@ -27,6 +27,7 @@
  *
  * @phpstan-import-type SfItem from StructuredField
  * @phpstan-import-type SfItemInput from StructuredField
+ * @phpstan-type SfInnerListPair array{0:iterable<SfItemInput>,b1:MemberOrderedMap<string, SfItem>|iterable<array{0:string, 1:SfItemInput}>}
  *
  * @implements MemberList<int, SfItem>
  */

src/Item.php

@@ -17,6 +17,7 @@
  *
  * @phpstan-import-type SfItem from StructuredField
  * @phpstan-import-type SfItemInput from StructuredField
+ * @phpstan-type SfItemPair array{0:ByteSequence|Token|DisplayString|DisplayString|DateTimeInterface|string|int|float|bool, 1:MemberOrderedMap<string, SfItem>|iterable<array{0:string, 1:SfItemInput}>}
  */
 final class Item implements ParameterAccess, ValueAccess
 {

src/OuterList.php

@@ -26,6 +26,8 @@
  *
  * @phpstan-import-type SfMember from StructuredField
  * @phpstan-import-type SfMemberInput from StructuredField
+ * @phpstan-import-type SfInnerListPair from InnerList
+ * @phpstan-import-type SfItemPair from Item
  *
  * @implements MemberList<int, SfMember>
  */
@@ -76,6 +78,19 @@ public static function fromHttpValue(Stringable|string $httpValue, ListParser $p
         return new self(...array_map($converter, $parser->parseList($httpValue)));
     }
 
+    /**
+     * @param iterable<SfInnerListPair|SfItemPair> $pairs
+     */
+    public static function fromPairs(iterable $pairs): self
+    {
+        $members = [];
+        foreach ($pairs as [$member, $parameters]) {
+            $members[] = is_iterable($member) ? InnerList::fromPair([$member, $parameters]) : Item::fromPair([$member, $parameters]);
+        }
+
+        return self::new(...$members);
+    }
+
     /**
      * @param SfMember|SfMemberInput ...$members
      */

src/functions.php

@@ -14,6 +14,7 @@
      * Parse a header conform to the HTTP Structured Field RFCs.
      *
      * @param 'dictionary'|'parameters'|'list'|'innerlist'|'item' $type
+     *
      * @throws OutOfRangeException If the value is unknown or undefined
      */
     function http_parse_structured_field(string $type, string $httpValue): StructuredField
@@ -24,7 +25,37 @@ function http_parse_structured_field(string $type, string $httpValue): Structure
             'list' => OuterList::fromHttpValue($httpValue),
             'innerlist' => InnerList::fromHttpValue($httpValue),
             'item' => Item::fromHttpValue($httpValue),  /* @phpstan-ignore-line */
-            default => throw new ValueError('The submitted type "'.$type.'" is unknown or not supported,'),  /* @phpstan-ignore-line */
+            default => throw new OutOfBoundsException('The submitted type "'.$type.'" is unknown or not supported,'),  /* @phpstan-ignore-line */
+        };
+    }
+}
+
+if (!function_exists('http_build_structured_field')) {
+    /**
+     * Build an HTTP Structured Field Text representation fron an iterable PHP structure.
+     *
+     * @param 'dictionary'|'parameters'|'list'|'innerlist'|'item' $type
+     * @param iterable $data the iterable data used to generate the structured field
+     *
+     * @throws OutOfBoundsException If the type is unknown or unsupported
+     *
+     * @see Dictionary::fromPairs()
+     * @see Parameters::fromPairs()
+     * @see OuterList::fromPairs()
+     * @see InnerList::fromPair()
+     * @see Item::fromPair()
+     */
+    function http_build_structured_field(string $type, iterable $data): string /* @phptan-ignore-line */
+    {
+        $data = [...$data];
+
+        return match ($type) {
+            'dictionary' => Dictionary::fromPairs($data)->toHttpValue(),
+            'parameters' => Parameters::fromPairs($data)->toHttpValue(),
+            'list' => OuterList::fromPairs($data)->toHttpValue(),
+            'innerlist' => InnerList::fromPair($data)->toHttpValue(), /* @phpstan-ignore-line */
+            'item' => Item::fromPair($data)->toHttpValue(), /* @phpstan-ignore-line */
+            default => throw new OutOfBoundsException('The submitted type "'.$type.'" is unknown or not supported,'),  /* @phpstan-ignore-line */
         };
     }
 }

tests/FunctionsTest.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bakame\Http\StructuredFields;
+
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class FunctionsTest extends TestCase
+{
+    #[Test]
+    public function ti_will_generate_the_structured_field_text_represenation_for_an_innerlist(): void
+    {
+        self::assertSame(
+            http_build_structured_field('innerlist', [['a', 'b', 'c'], [['a', true]]]),
+            InnerList::fromPair([['a', 'b', 'c'], [['a', true]]])->toHttpValue()
+        );
+    }
+
+    #[Test]
+    public function ti_will_generate_the_structured_field_text_represenation_for_an_item(): void
+    {
+        self::assertSame(
+            http_build_structured_field('item', ['coucoulesamis', [['a', false]]]),
+            Item::fromPair(['coucoulesamis', [['a', false]]])->toHttpValue()
+        );
+    }
+
+    #[Test]
+    public function ti_will_generate_the_structured_field_text_represenation_for_parameters(): void
+    {
+        $data = [['a', false], ['b', true]];
+
+        self::assertSame(
+            http_build_structured_field('parameters', $data),
+            Parameters::fromPairs($data)->toHttpValue()
+        );
+    }
+
+    #[Test]
+    public function ti_will_generate_the_structured_field_text_represenation_for_dictionary(): void
+    {
+        $data = [['a', false], ['b', Item::fromDateString('+30 minutes')]];
+
+        self::assertSame(
+            http_build_structured_field('dictionary', $data),
+            Dictionary::fromPairs($data)->toHttpValue()
+        );
+    }
+
+    #[Test]
+    public function ti_will_generate_the_structured_field_text_represenation_for_list(): void
+    {
+        $data = [
+            ['coucoulesamis', [['a', false]]],
+            [['a', 'b', Item::fromDateString('+30 minutes')], [['a', true]]],
+        ];
+
+        self::assertSame(
+            http_build_structured_field('list', $data),
+            OuterList::fromPairs($data)->toHttpValue() /* @phpstan-ignore-line */
+        );
+    }
+}