Update documentation v2

Author: nyamsprod

README.md

@@ -36,7 +36,7 @@ composer require bakame/http-structured-fields
 
 ## Documentation
 
-- The documentation for [version 2.x](/docs/00-intro.md) is a **work in progress**
+- The documentation for [version 2.x](/docs/00-intro.md) for **the upcoming v2 release**
 - The documentation for [version 1.x](https://github.com/bakame-php/http-structured-fields/tree/1.x) for the current stable version.
 
 ## Contributing

docs/00-intro.md

@@ -16,7 +16,7 @@ use Bakame\Http\StructuredFields\DataType;
 $fieldValue = 'text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8';
 $container = DataType::List->parse($fieldValue);
 $container[1]->value()->toString(); // returns 'application/xhtml+xml'
-$container[1]->parameterByName(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$container[1]->parameterByName(name: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
 ```
 
 ## Motivation

docs/04-item.md

@@ -64,15 +64,15 @@ They can be accessed by their indices **but also** by their required key attache
 
 $item = Item::fromHttpValue('application/xml;q=0.9;foobar');
 $item->value()->toString(); // returns 'application/xhtml+xml'
-$item->parameterByName(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$item->parameterByName(name: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
 $item->parameterByIndex(index: 1, default: ['toto', false]); // returns ['foobar', true] because there's a parameter at index 1
 $item->parameters(); // returns a Parameters instance.
 ```
 
 By default, you can access the member `Item` of a parameters using the following methods:
 
 - `Item::parameters` returns a `Parameters` instance;
-- `Item::parameterByName` returns the value of the bare item instance attached to the supplied `key`;
+- `Item::parameterByName` returns the value of the bare item instance attached to the supplied `name`;
 - `Item::parameterByIndex` returns the value of the bare item instance attached to the supplied `index`;
 
 It is possible to alter and modify the `Parameters` attached to an `Item` but this section

docs/05-containers.md

@@ -37,7 +37,7 @@ $permissions->isEmpty();      // returns false
 
 > [!IMPORTANT]
 > For ordered maps, the `getByIndex` method returns a list containing exactly 2 entries.
-> The first entry is the member key, the second entry is the member value.
+> The first entry is the member name, the second entry is the member value.
 > For lists, the method directly returns the value.
 
 To avoid invalid states, `ArrayAccess` modifying methods throw a `ForbiddenOperation`
@@ -51,24 +51,24 @@ unset($permissions['a']); // triggers a ForbiddenOperation exception
 ```
 
 > [!IMPORTANT]
-> For ordered map the ArrayAccess interface will use the member key
+> For ordered map the ArrayAccess interface will use the member name
 > whereas for lists the interface will use the member index.
 
-The `Dictionary` and `Parameters` classes also allow accessing its members as value using their key:
+The `Dictionary` and `Parameters` classes also allow accessing its members as value using their name:
 
 ```php
 $permissions->hasName('picture-in-picture');           // returns true
 $permissions->hasName('picture-in-picture', 'foobar'); // returns false 
-// 'foobar' is not a valid key or at least it is not present
+// 'foobar' is not a valid name or at least it is not present
 
 $permissions->getByName('camera'); // returns Item::fromToken('*');
 $permissions->toAssociative(); // returns an iterator
-// the iterator key is the member key and the value is the member value
+// the iterator key is the member name and the value is the member value
 // the offset is "lost"
 $permissions->nameByIndex(42); // returns null because there's no member with the offset 42
 $permissions->nameByIndex(2);  // returns 'camera'
 
-$permissions->indexByName('foobar'): // returns null because there's no member with the key 'foobar'
+$permissions->indexByName('foobar'): // returns null because there's no member with the name 'foobar'
 $permissions->indexByName('geolocation'): // returns 1
 ```
 
@@ -89,7 +89,7 @@ On the other hand if you already have a `Parameters` instance you can use the
 parameter.
 
 > [!TIP]
-> The `parameterByKey` proxy the result from `valueByName`.
+> The `parameterByName` proxy the result from `valueByName`.
 > The `parameterByIndex` proxy the result from `valueByIndex`.
 
 ## Building and Updating Structured Fields Values
@@ -172,14 +172,14 @@ using indices and pair as described in the RFC.
 
 The `$pair` parameter is a tuple (ie: an array as list with exactly two members) where:
 
-- the first array member is the parameter `$key`
+- the first array member is the parameter `$name`
 - the second array member is the parameter `$value`
 
 ```php
 $map->unshift(array ...$pairs): static;
 $map->push(array ...$pairs): static;
-$map->insert(int $key, array ...$pairs): static;
-$map->replace(int $key, array $pair): static;
+$map->insert(int $name, array ...$pairs): static;
+$map->replace(int $name, array $pair): static;
 $map->mergePairs(...$others): static;
 $map->removeByIndices(int ...$indices): static;
 ```
@@ -292,9 +292,9 @@ named constructor and the use any of the following modifying methods.
 ```php
 $list->unshift(...$members): static;
 $list->push(...$members): static;
-$list->insert(int $key, ...$members): static;
-$list->replace(int $key, $member): static;
-$list->removeByIndices(int ...$key): static;
+$list->insert(int $index, ...$members): static;
+$list->replace(int $index, $member): static;
+$list->removeByIndices(int ...$index): static;
 ```
 
 as shown below
@@ -387,7 +387,7 @@ You can attach and update the associated `Parameters` instance using the followi
 $field->addParameter(string $name, mixed $value): static;
 $field->appendParameter(string $name, mixed $value): static;
 $field->prependParameter(string $name, mixed $value): static;
-$field->withoutParameters(string ...$names): static; // this method is deprecated as of version 1.1 use withoutParametersByKeys instead
+$field->withoutParametersByNames(string ...$names): static;
 $field->withoutAnyParameter(): static;
 $field->withParameters(Parameters $parameters): static;
 $field->pushParameters(array ...$pairs): static
@@ -400,7 +400,7 @@ $field->withoutParametersByIndices(int ...$indices): static
 
 The `$pair` parameter is a tuple (ie: an array as list with exactly two members) where:
 
-- the first array member is the parameter `$key`
+- the first array member is the parameter `$name`
 - the second array member is the parameter `$value`
 
 > [!WARNING]

docs/06-validation.md

@@ -85,7 +85,7 @@ following variables:
 
 - `{index}` the member index
 - `{value}` the member value in its serialized version
-- `{key}` the member key (only available with `Dictionary` and `Parameters`)
+- `{name}` the member name (only available with `Dictionary` and `Parameters`)
 
 Now that we know how to discriminate between an `InnerList` and a `Item` we want to validate
 the `Item` entry.
@@ -163,8 +163,8 @@ if (!$member->parameters()->allowedNames(['location', 'longitude', 'latitude', '
 
 ### Validating single parameters
 
-The `parameterByKey` and `parameterByIndex` methods can be used to validate a parameter value.
-Since in our field there is no mention of offset, we will use the `::parameterByKey` method.
+The `parameterByName` and `parameterByIndex` methods can be used to validate a parameter value.
+Since in our field there is no mention of offset, we will use the `::parameterByName` method.
 
 Let's try to validate the `longitude` parameter
 
@@ -173,18 +173,18 @@ require its presence. So to fully validate the parameter we need to do the follo
 
 ```php
 $member->parameterByName(
-    key: 'longitude',
+    name: 'longitude',
     validate: fn (mixed $value) => match (true) {
         Type::Decimal->supports($value) => true,
-        default => "The `{key}` '{value}' failed the validation check."
+        default => "The `{name}` '{value}' failed the validation check."
     },
     required: true,
 );
 ```
 
 > [!NOTE]
 > `parameterByIndex` uses the same parameter only the callback parameter are
-> different as a second parameter the string key is added to the callback
+> different as a second parameter the string name is added to the callback
 > for validation purpose.
 
 ### Validating the complete Parameter container
@@ -220,9 +220,9 @@ $parametersValidator = ParametersValidator::new()
 
 The `ParametersValidator` class is immutable so each added rules returns a new instance.
 
-Then we can add all the key checks using an associative `array` where each entry index
-will be the parameter `key` and each entry value will also be an array which takes
-the parameters of the `parameterByKey` method. For instance for the `longitude` parameter
+Then we can add all the name checks using an associative `array` where each entry index
+will be the parameter `name` and each entry value will also be an array which takes
+the parameters of the `parameterByName` method. For instance for the `longitude` parameter
 we did earlier we end up with the following entries.
 
 ```php
@@ -232,7 +232,7 @@ $parametersValidator = ->filterByNames([
         'longitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
-                    return "The `{key}` '{value}' failed the validation check.";
+                    return "The `{name}` '{value}' failed the validation check.";
                  }
 
                  return true; 
@@ -266,7 +266,7 @@ $parametersValidator = ParametersValidator::new()
         'longitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
-                    return "The `{key}` '{value}' failed the validation check.";
+                    return "The `{name}` '{value}' failed the validation check.";
                  }
 
                  return true; 
@@ -276,7 +276,7 @@ $parametersValidator = ParametersValidator::new()
         'latitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
-                    return "The `{key}` '{value}' failed the validation check.";
+                    return "The `{name}` '{value}' failed the validation check.";
                  }
 
                  return true; 
@@ -286,7 +286,7 @@ $parametersValidator = ParametersValidator::new()
         'date' => [
             'validate' => function (mixed $value) {
                  if (!Type::Date->supports($value)) {
-                    return "The `{key}` '{value}' is not a valid date";
+                    return "The `{name}` '{value}' is not a valid date";
                  }
 
                  return true; 

docs/07-extensions.md

@@ -34,9 +34,9 @@ On the other hand to allow composition the package does expose the `StructuredFi
 interface StructuredFieldProvider
 {
     /**
-     * Returns ane of the StructuredField Data Type class.
+     * Returns one of the StructuredField Data Type class.
      */
-    public function toStructuredField(): OuterList|Dictionary|Item|InnerList|Parameters;
+    public function toStructuredField(): Dictionary|InnerList|Item|OuterList|Parameters;
 }
 ```
 

src/Dictionary.php

@@ -59,8 +59,11 @@ private static function filterMember(mixed $member): InnerList|Item
         }
 
         return match (true) {
-            $member instanceof InnerList || $member instanceof Item => $member,
-            $member instanceof OuterList || $member instanceof Dictionary || $member instanceof Parameters => throw new InvalidArgument('An instance of "'.$member::class.'" can not be a member of "'.self::class.'".'),
+            $member instanceof InnerList,
+            $member instanceof Item => $member,
+            $member instanceof OuterList,
+            $member instanceof Dictionary,
+            $member instanceof Parameters => throw new InvalidArgument('An instance of "'.$member::class.'" can not be a member of "'.self::class.'".'),
             is_iterable($member) => InnerList::new(...$member),
             default => Item::new($member),
         };

src/InnerList.php

@@ -351,7 +351,7 @@ public function removeByIndices(int ...$indices): self
             count($indices) === $max => self::new(),
             default => new self(array_filter(
                 $this->members,
-                fn (int $key): bool => !in_array($key, $indices, true),
+                fn (int $offset): bool => !in_array($offset, $indices, true),
                 ARRAY_FILTER_USE_KEY
             ), $this->parameters),
         };

src/OuterList.php

@@ -60,8 +60,11 @@ private function filterMember(mixed $member): InnerList|Item
         }
 
         return match (true) {
-            $member instanceof InnerList || $member instanceof Item => $member,
-            $member instanceof OuterList || $member instanceof Parameters || $member instanceof Dictionary => throw new InvalidArgument('An instance of "'.$member::class.'" can not be a member of "'.self::class.'".'),
+            $member instanceof InnerList,
+            $member instanceof Item => $member,
+            $member instanceof OuterList,
+            $member instanceof Parameters,
+            $member instanceof Dictionary => throw new InvalidArgument('An instance of "'.$member::class.'" can not be a member of "'.self::class.'".'),
             is_iterable($member) => InnerList::new(...$member),
             default => Item::new($member),
         };

src/StructuredFieldProvider.php

@@ -8,7 +8,7 @@
 use DateTimeInterface;
 
 /**
- * @phpstan-type StructuredField OuterList|Dictionary|InnerList|Parameters|Item
+ * @phpstan-type StructuredField Dictionary|InnerList|Item|OuterList|Parameters
  * @phpstan-type SfType ByteSequence|Token|DisplayString|DateTimeImmutable|string|int|float|bool
  * @phpstan-type SfTypeInput SfType|DateTimeInterface
  * @phpstan-type SfItemInput Item|SfTypeInput|StructuredFieldProvider|StructuredField
@@ -20,7 +20,7 @@
 interface StructuredFieldProvider
 {
     /**
-     * Returns ane of the StructuredField Data Type class.
+     * Returns one of the StructuredField Data Type class.
      */
-    public function toStructuredField(): OuterList|Dictionary|Item|InnerList|Parameters;
+    public function toStructuredField(): Dictionary|InnerList|Item|OuterList|Parameters;
 }