Using key instead of name for POLA

Author: nyamsprod

README.md

@@ -19,7 +19,7 @@ use Bakame\Http\StructuredFields\OuterList;
 $fieldValue = 'text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8';
 $container = OuterList::fromRfc9651($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]->parameterByKey(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
 ```
 
 ## System Requirements

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(name: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$container[1]->parameterByKey(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
 ```
 
 ## Motivation

docs/02-parsing-serializing.md

@@ -128,9 +128,9 @@ The following field is an example from the Accept header which is already struct
 $fieldValue = 'text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8';
 $field = DataType::List->parse($fieldValue);
 $field[2]->value()->toString(); // returns 'application/xml'
-$field[2]->parameterByName('q'); // returns (float) 0.9
+$field[2]->parameterByKey('q'); // returns (float) 0.9
 $field[0]->value()->toString(); // returns 'text/html'
-$field[0]->parameterByName('q'); // returns null
+$field[0]->parameterByKey('q'); // returns null
 ```
 
 - The Accept header is an `List` field made of `Item` only.

docs/03-field-values.md

@@ -182,15 +182,15 @@ They can be accessed by their indices **but also** by their **required key** att
 
 $item = Item::fromHttpValue('application/xml;q=0.9;foobar');
 $item->value()->toString(); // returns 'application/xhtml+xml'
-$item->parameterByName(name: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$item->parameterByKey(key: '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 `name`;
+- `Item::parameterByKey` 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 will be explored in

docs/04-containers.md

@@ -48,7 +48,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 name, the second entry is the member value.
+> The first entry is the member key, 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`
@@ -68,39 +68,39 @@ unset($permissions['a']); // triggers a ForbiddenOperation exception
 The `Dictionary` and `Parameters` classes also allow accessing their members as value using their name:
 
 ```php
-$permissions->hasName('picture-in-picture');           // returns true
-$permissions->hasName('picture-in-picture', 'foobar'); // returns false 
+$permissions->hasKey('picture-in-picture');           // returns true
+$permissions->hasKey('picture-in-picture', 'foobar'); // returns false 
 // 'foobar' is not a valid name or at least it is not present
 
-$permissions->getByName('camera'); // returns Item::fromToken('*');
+$permissions->getByKey('camera'); // returns Item::fromToken('*');
 $permissions->toAssociative(); // returns an iterator
 // 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->keyByIndex(42); // returns null because there's no member with the offset 42
+$permissions->keyByIndex(2);  // returns 'camera'
 
-$permissions->indexByName('foobar'): // returns null because there's no member with the name 'foobar'
-$permissions->indexByName('geolocation'): // returns 1
+$permissions->indexByKey('foobar'): // returns null because there's no member with the name 'foobar'
+$permissions->indexByKey('geolocation'): // returns 1
 ```
 
 > [!IMPORTANT]
-> The `getByName` method will throw an `InvalidOffset` exception if no member exists for the given `$offset`.
+> The `getByKey` method will throw an `InvalidOffset` exception if no member exists for the given `$offset`.
 
 > [!TIP]
 > The `ArrayAccess` interface proxy the result from `getByIndex` and `hasIndices` with `OuterList` and `InnerList`.
-> The `ArrayAccess` interface proxy the result from `getByName` and `hasNames` with `Dictionary` and `Parameters`.
+> The `ArrayAccess` interface proxy the result from `getByNKey` and `hasKeys` with `Dictionary` and `Parameters`.
 
 ### Accessing the parameters values
 
 As we have already seen, it is possible to access the `Parameters` values directly
 from the `Item` instance. The same public API is used for the `InnerList`.
 
 On the other hand if you already have a `Parameters` instance you can use the
-`valueByName` and `valueByIndex` methods to directly access the value from a single
+`valueByKey` and `valueByIndex` methods to directly access the value from a single
 parameter.
 
 > [!TIP]
-> The `parameterByName` proxy the result from `valueByName`.
+> The `parameterByKey` proxy the result from `valueByKey`.
 > The `parameterByIndex` proxy the result from `valueByIndex`.
 
 ## Building and Updating Containers
@@ -149,11 +149,11 @@ following steps. You, first, create a `Parameters` or a `Dictionary` instance us
 use any of the following modifying methods to populate it.
 
 ```php
-$map->add(string $name, $value): static;
-$map->append(string $name, $value): static;
-$map->prepend(string $name, $value): static;
+$map->add(string $key, $value): static;
+$map->append(string $key, $value): static;
+$map->prepend(string $key, $value): static;
 $map->mergeAssociative(...$others): static;
-$map->removeByNames(string ...$names): static;
+$map->removeByKeys(string ...$keys): static;
 ```
 
 As shown below:
@@ -183,14 +183,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 `$name`
+- the first array member is the parameter `$key`
 - the second array member is the parameter `$value`
 
 ```php
 $map->unshift(array ...$pairs): static;
 $map->push(array ...$pairs): static;
-$map->insert(int $name, array ...$pairs): static;
-$map->replace(int $name, array $pair): static;
+$map->insert(int $index, array ...$pairs): static;
+$map->replace(int $index, array $pair): static;
 $map->mergePairs(...$others): static;
 $map->removeByIndices(int ...$indices): static;
 ```
@@ -223,15 +223,15 @@ echo $value;                //b=?0, a=(bar "42" 42 42.0), c=@1671800423
 > [!CAUTION]
 > on duplicate `names` pair values are merged as per RFC logic.
 
-The following methods `removeByIndices` and/or `removeByNames` allow removing members
+The following methods `removeByIndices` and/or `removeByKeys` allow removing members
 per indices or per names.
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
 
 $field = Parameters::fromHttpValue(';expire=@1681504328;path="/";max-age=2500;secure;httponly=?0;samesite=lax');
 echo $field->removeByIndices(4, 2, 0)->toHttpValue();                      // returns ;path="/";secure;samesite=lax
-echo $field->removeByNames('expire', 'httponly', 'max-age')->toHttpValue(); // returns ;path="/";secure;samesite=lax
+echo $field->removeByKeys('expire', 'httponly', 'max-age')->toHttpValue(); // returns ;path="/";secure;samesite=lax
 ```
 
 ### Automatic conversion
@@ -396,21 +396,21 @@ You can attach and update the associated `Parameters` instance using the followi
 
 ```php
 $field->withParameters(Parameters $parameters): static;
-$field->addParameter(string $name, mixed $value): static;
-$field->appendParameter(string $name, mixed $value): static;
-$field->prependParameter(string $name, mixed $value): static;
+$field->addParameter(string $key, mixed $value): static;
+$field->appendParameter(string $key, mixed $value): static;
+$field->prependParameter(string $key, mixed $value): static;
 $field->pushParameters(array ...$pairs): static
 $field->unshiftParameters(array ...$pairs): static
 $field->insertParameters(int $index, array ...$pairs): static
 $field->replaceParameter(int $index, array $pair): static
-$field->withoutParametersByNames(string ...$names): static
+$field->withoutParametersByKeys(string ...$keys): static
 $field->withoutParametersByIndices(int ...$indices): static
 $field->withoutAnyParameter(): static;
 ```
 
 The `$pair` parameter is an array as list with exactly two members where:
 
-- the first array member is the parameter `$name`
+- the first array member is the parameter `$key`
 - the second array member is the parameter `$value`
 
 > [!WARNING]

docs/05-validation.md

@@ -85,7 +85,7 @@ following variables:
 
 - `{index}` the member index
 - `{value}` the member value in its serialized version
-- `{name}` the member name (only available with `Dictionary` and `Parameters`)
+- `{key}` 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.
@@ -150,33 +150,33 @@ to the item are: `location`, `longitude`, `latitude` and `date`
 ```php
 use Bakame\Http\StructuredFields\Validation\Violation;
 
-if (!$member->parameters()->allowedNames(['location', 'longitude', 'latitude', 'date'])) {
+if (!$member->parameters()->allowedKeys(['location', 'longitude', 'latitude', 'date'])) {
     throw new Violation('The parameters contains extra names that are not allowed.');
 }
 ```
 
 > [!TIP]
-> The `Dictionary` class also exposes an `allowedNames` method which behave the same way.
+> The `Dictionary` class also exposes an `allowedKeys` method which behave the same way.
 
 > [!WARNING]
 > if the parameters container is empty no error will be triggered
 
 ### Validating single parameters
 
 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.
+Since in our field there is no mention of offset, we will use the `::parameterByKey` method.
 
 Let's try to validate the `longitude` parameter
 
 Because parameters are optional by default and the `longitude` parameter is required we must
 require its presence. So to fully validate the parameter we need to do the following
 
 ```php
-$member->parameterByName(
+$member->parameterByKey(
     name: 'longitude',
     validate: fn (mixed $value) => match (true) {
         Type::Decimal->supports($value) => true,
-        default => "The `{name}` '{value}' failed the validation check."
+        default => "The `{key}` '{value}' failed the validation check."
     },
     required: true,
 );
@@ -214,7 +214,7 @@ expects the `Parameters` container as its sole argument.
 ```php
 $parametersValidator = ParametersValidator::new()
     ->filterByCriteria(function (Parameters $parameters): bool|string {
-        return $parameters->allowedNames(['location', 'longitude', 'latitude', 'date']);
+        return $parameters->alloweKeys(['location', 'longitude', 'latitude', 'date']);
     });
 ```
 
@@ -228,11 +228,11 @@ we did earlier we end up with the following entries.
 ```php
 use Bakame\Http\StructuredFields\Type;
 
-$parametersValidator = ->filterByNames([
+$parametersValidator = ->filterByKeys([
         'longitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
-                    return "The `{name}` '{value}' failed the validation check.";
+                    return "The `{key}` '{value}' failed the validation check.";
                  }
 
                  return true; 
@@ -257,16 +257,16 @@ use Bakame\Http\StructuredFields\Validation\ParametersValidator;
 $parametersValidator = ParametersValidator::new()
     ->filterByCriteria(
         fn (Parameters $parameters): bool|string => $parameters
-            ->allowedNames(['location', 'longitude', 'latitude', 'date'])
+            ->allowedKeys(['location', 'longitude', 'latitude', 'date'])
     )
-    ->filterByNames([
+    ->filterByKeys([
         'location' => [
             'validate' => fn (mixed $value) => Type::fromVariable($value)->isOneOf(Type::String, Type::DisplayString),
         ],
         'longitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
-                    return "The `{name}` '{value}' failed the validation check.";
+                    return "The `{key}` '{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 `{name}` '{value}' failed the validation check.";
+                    return "The `{key}` '{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 `{name}` '{value}' is not a valid date";
+                    return "The `{key}` '{value}' is not a valid date";
                  }
 
                  return true; 
@@ -329,7 +329,7 @@ if ($validation->isSucces()) {
 > [!NOTE]
 > If we only use the `filterByCriteria` method the full parameter data is returned.
 
- A `filterByIndices` method exists and behave exactly as the `filterByNames` method.
+ A `filterByIndices` method exists and behave exactly as the `filterByKeys` method.
 There are two differences when it is used:
 
 - The callback parameters are different (they match those of `parameterByIndex`)

docs/08-migration.md

@@ -27,7 +27,7 @@ This will edit (or create) your `composer.json` file.
 
 ### Structured Field Interfaces
 
-All the Interfaces around the structured field data types are remove. So if you typehinted your code using
+All the Interfaces around the structured field data types are removed. So if you type-hinted your code using
 the interfaces, you will need to replace them by their actual implementation.
 
 - The `MemberOrderedMap` interface will need to be replaced either by `Dictionary` or `Parameters` classes
@@ -45,7 +45,7 @@ facing public API.
 + public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
 ```
 
-In v2, the parser instance is replaced by a enum that indicates which RFC should be used for parsing.
+In v2, the parser instance is replaced by an Enum that indicates which RFC should be used for parsing.
 If your code did not provide any second parameter to the method then the parsing will be done using `RFC9651`
 if you want to only consider the previous active RFC, then you will have to explicitly name it via the `Ietf` Enum.
 
@@ -54,32 +54,26 @@ if you want to only consider the previous active RFC, then you will have to expl
 `Dictionary` and `Parameters` container members can be accessed vi their name or via their index.
 To normalize the accessor methods the following changes were introduced
 
-| `1.x` method name                   | `2.x` method name                    |
-|-------------------------------------|--------------------------------------|
-| `Item::parameter`                   | `Item::parameterByName`              |
-| `Item::withoutParamtersByKeys`      | `Item::withoutParamtersByNames`      |
-| `InnerList::parameter`              | `InnerList::parameterByName`         |
-| `InnerList::withoutParamtersByKeys` | `InnerList::withoutParamtersByNames` |
-| `InnerList::has`                    | `InnerList::hasIndices`              |
-| `InnerList::get`                    | `InnerList::getIndex`                |
-| `OuterList::get`                    | `OuterList::getIndex`                |
-| `OuterList::has`                    | `OuterList::hasIndices`              |
-| `Dictionary::has`                   | `Dictionary::hasNames`               |
-| `Dictionary::keys`                  | `Dictionary::names`                  |
-| `Dictionary::get`                   | `Dictionary::getByName`              |
-| `Dictionary::removeByKeys`          | `Dictionary::removeByNames`          |
-| `Dictionary::pair`                  | `Dictionary::getByIndex`             |
-| `Parameters::has`                   | `Parameters::hasNames`               |
-| `Parameters::keys`                  | `Parameters::names`                  |
-| `Parameters::get`                   | `Parameters::getByName`              |
-| `Parameters::pair`                  | `Parameters::getByIndex`             |
-| `Parameters::removeByKeys`          | `Parameters::removeByNames`          |
-| `Container::remove`                 | `Container::removeByIndices`         |
-| `Container::hasNoMember`            | `Container::isEmpty`                 |
-| `Container::hasMembers`             | `Container::isNotEmpty`              |
+| `1.x` method name                   | `2.x` method name            |
+|-------------------------------------|------------------------------|
+| `Item::parameter`                   | `Item::parameterByKey`       |
+| `InnerList::parameter`              | `InnerList::parameterByKey`  |
+| `InnerList::has`                    | `InnerList::hasIndices`      |
+| `InnerList::get`                    | `InnerList::getIndex`        |
+| `OuterList::get`                    | `OuterList::getIndex`        |
+| `OuterList::has`                    | `OuterList::hasIndices`      |
+| `Dictionary::has`                   | `Dictionary::hasKeys`        |
+| `Dictionary::get`                   | `Dictionary::getByKey`       |
+| `Dictionary::pair`                  | `Dictionary::getByIndex`     |
+| `Parameters::has`                   | `Parameters::hasKeys`        |
+| `Parameters::get`                   | `Parameters::getByKey`       |
+| `Parameters::pair`                  | `Parameters::getByIndex`     |
+| `Container::remove`                 | `Container::removeByIndices` |
+| `Container::hasNoMember`            | `Container::isEmpty`         |
+| `Container::hasMembers`             | `Container::isNotEmpty`      |
 
 The `Parameters::remove` and `Dictionary::remove` methods are removed from the public API, they
-were accepting `indices` and `names` indiscriminately which may lead to subtle bugs in code.
+were accepting `indices` and `keys` indiscriminately which may lead to subtle bugs in code.
 
 ## Behaviour changes