Move docblock under the StructuredFieldProvider class

bakame-php · Nov 18, 2024 · 329a28d · 329a28d
1 parent 9a6f75d
commit 329a28d
Show file tree

Hide file tree

Showing 14 changed files with 48 additions and 38 deletions.
diff --git a/src/Dictionary.php b/src/Dictionary.php
@@ -26,7 +26,7 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.2
  *
- * @phpstan-import-type SfMemberInput from StructuredField
+ * @phpstan-import-type SfMemberInput from StructuredFieldProvider
  *
  * @implements ArrayAccess<string, InnerList|Item>
  * @implements IteratorAggregate<int, array{0:string, 1:InnerList|Item}>

diff --git a/src/InnerList.php b/src/InnerList.php
@@ -27,10 +27,10 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.1.1
  *
- * @phpstan-import-type SfType from StructuredField
- * @phpstan-import-type SfItemInput from StructuredField
- * @phpstan-import-type SfInnerListPair from StructuredField
- * @phpstan-import-type SfParameterInput from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
+ * @phpstan-import-type SfItemInput from StructuredFieldProvider
+ * @phpstan-import-type SfInnerListPair from StructuredFieldProvider
+ * @phpstan-import-type SfParameterInput from StructuredFieldProvider
  *
  * @implements  ArrayAccess<int, Item>
  * @implements  IteratorAggregate<int, Item>

diff --git a/src/Item.php b/src/Item.php
@@ -16,10 +16,10 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.3
  *
- * @phpstan-import-type SfType from StructuredField
- * @phpstan-import-type SfItemInput from StructuredField
- * @phpstan-import-type SfItemPair from StructuredField
- * @phpstan-import-type SfTypeInput from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
+ * @phpstan-import-type SfItemInput from StructuredFieldProvider
+ * @phpstan-import-type SfItemPair from StructuredFieldProvider
+ * @phpstan-import-type SfTypeInput from StructuredFieldProvider
  */
 final class Item implements StructuredField
 {

diff --git a/src/OuterList.php b/src/OuterList.php
@@ -29,9 +29,9 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#name-lists
  *
- * @phpstan-import-type SfMemberInput from StructuredField
- * @phpstan-import-type SfInnerListPair from StructuredField
- * @phpstan-import-type SfItemPair from StructuredField
+ * @phpstan-import-type SfMemberInput from StructuredFieldProvider
+ * @phpstan-import-type SfInnerListPair from StructuredFieldProvider
+ * @phpstan-import-type SfItemPair from StructuredFieldProvider
  *
  * @implements ArrayAccess<int, InnerList|Item>
  * @implements IteratorAggregate<int, InnerList|Item>

diff --git a/src/ParameterAccess.php b/src/ParameterAccess.php
@@ -12,8 +12,8 @@
  * Common manipulation methods used when interacting with an object
  * with a Parameters instance attached to it.
  *
- * @phpstan-import-type SfType from StructuredField
- * @phpstan-import-type SfItemInput from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
+ * @phpstan-import-type SfItemInput from StructuredFieldProvider
  */
 trait ParameterAccess
 {

diff --git a/src/Parameters.php b/src/Parameters.php
@@ -26,8 +26,8 @@
 /**
  * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.1.2
  *
- * @phpstan-import-type SfItemInput from StructuredField
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfItemInput from StructuredFieldProvider
+ * @phpstan-import-type SfType from StructuredFieldProvider
  *
  * @implements ArrayAccess<string, InnerList|Item>
  * @implements IteratorAggregate<int, array{0:string, 1:Item}>

diff --git a/src/Parser.php b/src/Parser.php
@@ -33,7 +33,7 @@
  * @internal Do not use directly this class as it's behaviour and return type
  *           MAY change significantly even during a major release cycle.
  *
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
  */
 final class Parser
 {

diff --git a/src/StructuredField.php b/src/StructuredField.php
@@ -4,25 +4,15 @@
 
 namespace Bakame\Http\StructuredFields;
 
-use DateTimeImmutable;
-use DateTimeInterface;
 use Stringable;
 
 /**
  * @internal The interface MUST not be implemented outside the package codebase
- *
- * @phpstan-type SfType ByteSequence|Token|DisplayString|DateTimeImmutable|string|int|float|bool
- * @phpstan-type SfTypeInput SfType|DateTimeInterface
- * @phpstan-type SfItemInput Item|SfTypeInput|StructuredFieldProvider|StructuredField
- * @phpstan-type SfMemberInput iterable<SfItemInput>|SfItemInput
- * @phpstan-type SfParameterInput iterable<array{0:string, 1?:SfItemInput}>
- * @phpstan-type SfInnerListPair array{0:iterable<SfItemInput>, 1?:Parameters|SfParameterInput}
- * @phpstan-type SfItemPair array{0:SfTypeInput, 1?:Parameters|SfParameterInput}
  */
 interface StructuredField extends Stringable
 {
     /**
-     * Returns a new instance from an HTTP Header or Trailer value string in compliance to an accepted RFC.
+     * Returns a new instance from an HTTP Header or Trailer value string in compliance to an RFC.
      *
      * @throws StructuredFieldError If the HTTP value can not be parsed
      */
@@ -38,8 +28,16 @@ public function toHttpValue(?Ietf $rfc = null): string;
     /**
      * Returns the serialize-representation of the Structured Field as a textual HTTP field value
      * using the last accepted RFC protocol.
-     *
-     * @throws StructuredFieldError If the object can not be serialized
      */
     public function __toString(): string;
+
+    /**
+     * Tells whether the object is identical as the one submitted.
+     * Returns true on success, false otherwise.
+     *
+     * Two objects are considered equals if they are instance of the same class
+     * and if their serialize-representation of the Structured Field as a
+     * textual HTTP field value is identical.
+     */
+    public function equals(mixed $other): bool;
 }
diff --git a/src/StructuredFieldProvider.php b/src/StructuredFieldProvider.php
@@ -4,6 +4,18 @@
 
 namespace Bakame\Http\StructuredFields;
 
+use DateTimeImmutable;
+use DateTimeInterface;
+
+/**
+ * @phpstan-type SfType ByteSequence|Token|DisplayString|DateTimeImmutable|string|int|float|bool
+ * @phpstan-type SfTypeInput SfType|DateTimeInterface
+ * @phpstan-type SfItemInput Item|SfTypeInput|StructuredFieldProvider|StructuredField
+ * @phpstan-type SfMemberInput iterable<SfItemInput>|SfItemInput
+ * @phpstan-type SfParameterInput iterable<array{0:string, 1?:SfItemInput}>
+ * @phpstan-type SfInnerListPair array{0:iterable<SfItemInput>, 1?:Parameters|SfParameterInput}
+ * @phpstan-type SfItemPair array{0:SfTypeInput, 1?:Parameters|SfParameterInput}
+ */
 interface StructuredFieldProvider
 {
     /**

diff --git a/src/Validation/ItemValidator.php b/src/Validation/ItemValidator.php
@@ -5,14 +5,14 @@
 namespace Bakame\Http\StructuredFields\Validation;
 
 use Bakame\Http\StructuredFields\Item;
-use Bakame\Http\StructuredFields\StructuredField;
+use Bakame\Http\StructuredFields\StructuredFieldProvider;
 use Bakame\Http\StructuredFields\SyntaxError;
 use Stringable;
 
 /**
  * Structured field Item validator.
  *
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
  */
 final class ItemValidator
 {

diff --git a/src/Validation/ParametersValidator.php b/src/Validation/ParametersValidator.php
@@ -5,14 +5,14 @@
 namespace Bakame\Http\StructuredFields\Validation;
 
 use Bakame\Http\StructuredFields\Parameters;
-use Bakame\Http\StructuredFields\StructuredField;
+use Bakame\Http\StructuredFields\StructuredFieldProvider;
 use Bakame\Http\StructuredFields\SyntaxError;
 use Stringable;
 
 /**
  * Structured field Item validator.
  *
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
  *
  * @phpstan-type SfParameterKeyRule array{validate?:callable(SfType): (bool|string), required?:bool|string, default?:SfType|null}
  * @phpstan-type SfParameterIndexRule array{validate?:callable(SfType, string): (bool|string), required?:bool|string, default?:array{0:string, 1:SfType}|array{}}

diff --git a/src/Validation/ValidatedParameters.php b/src/Validation/ValidatedParameters.php
@@ -7,13 +7,13 @@
 use ArrayAccess;
 use Bakame\Http\StructuredFields\ForbiddenOperation;
 use Bakame\Http\StructuredFields\InvalidOffset;
-use Bakame\Http\StructuredFields\StructuredField;
+use Bakame\Http\StructuredFields\StructuredFieldProvider;
 use Countable;
 use Iterator;
 use IteratorAggregate;
 
 /**
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
  *
  * @implements ArrayAccess<array-key, array{0:string, 1:SfType}|array{}|SfType|null>
  * @implements IteratorAggregate<array-key, array{0:string, 1:SfType}|array{}|SfType|null>

diff --git a/tests/ItemTest.php b/tests/ItemTest.php
@@ -14,7 +14,7 @@
 use Stringable;
 
 /**
- * @phpstan-import-type SfItemInput from StructuredField
+ * @phpstan-import-type SfItemInput from StructuredFieldProvider
  */
 final class ItemTest extends StructuredFieldTestCase
 {

diff --git a/tests/ParserTest.php b/tests/ParserTest.php
@@ -9,7 +9,7 @@
 use PHPUnit\Framework\Attributes\Test;
 
 /**
- * @phpstan-import-type SfType from StructuredField
+ * @phpstan-import-type SfType from StructuredFieldProvider
  */
 final class ParserTest extends StructuredFieldTestCase
 {