Use name instead of getByValue (#18)

Use name instead of key

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]->parameterByKey(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$container[1]->parameterByName(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]->parameterByKey(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$container[1]->parameterByName(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]->parameterByKey('q'); // returns (float) 0.9
+$field[2]->parameterByName('q'); // returns (float) 0.9
 $field[0]->value()->toString(); // returns 'text/html'
-$field[0]->parameterByKey('q'); // returns null
+$field[0]->parameterByName('q'); // returns null
 ```
 
 - The Accept header is an `List` field made of `Item` only.

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->parameterByKey(key: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$item->parameterByName(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::parameterByKey` 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 `key`;
 - `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

@@ -57,39 +57,39 @@ unset($permissions['a']); // triggers a ForbiddenOperation exception
 The `Dictionary` and `Parameters` classes also allow accessing its members as value using their key:
 
 ```php
-$permissions->hasKey('picture-in-picture');           // returns true
-$permissions->hasKey('picture-in-picture', 'foobar'); // returns false 
+$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
 
-$permissions->getByKey('camera'); // returns Item::fromToken('*');
+$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 offset is "lost"
-$permissions->keyByIndex(42); // returns null because there's no member with the offset 42
-$permissions->keyByIndex(2);  // returns 'camera'
+$permissions->nameByIndex(42); // returns null because there's no member with the offset 42
+$permissions->nameByIndex(2);  // returns 'camera'
 
-$permissions->indexByKey('foobar'): // returns null because there's no member with the key 'foobar'
-$permissions->indexByKey('geolocation'): // returns 1
+$permissions->indexByName('foobar'): // returns null because there's no member with the key 'foobar'
+$permissions->indexByName('geolocation'): // returns 1
 ```
 
 > [!IMPORTANT]
-> The `getByKey` method will throw an `InvalidOffset` exception if no member exists for the given `$offset`.
+> The `getByName` method will throw an `InvalidOffset` exception if no member exists for the given `$offset`.
 
 > [!TIP]
 > The `ArrayAccess` interface proxy the result from `getByIndex` in list.
-> The `ArrayAccess` interface proxy the result from `getByKey` in ordered map.
+> The `ArrayAccess` interface proxy the result from `getByName` in ordered map.
 
 ### 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 from the `InnerList`.
 
 On the other hand if you already have a `Parameters` instance you can use the
-`valueByKey` and `valueByIndex` methods to directly access the value from a single
+`valueByName` and `valueByIndex` methods to directly access the value from a single
 parameter.
 
 > [!TIP]
-> The `parameterByKey` proxy the result from `valueByKey`.
+> The `parameterByKey` proxy the result from `valueByName`.
 > The `parameterByIndex` proxy the result from `valueByIndex`.
 
 ## Building and Updating Structured Fields Values
@@ -138,11 +138,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 $key, $value): static;
-$map->append(string $key, $value): static;
-$map->prepend(string $key, $value): static;
+$map->add(string $name, $value): static;
+$map->append(string $name, $value): static;
+$map->prepend(string $name, $value): static;
 $map->mergeAssociative(...$others): static;
-$map->removeByKeys(string ...$keys): static;
+$map->removeByKeys(string ...$names): static;
 ```
 
 As shown below:
@@ -384,9 +384,9 @@ Both objects provide additional modifying methods to help deal with parameters.
 You can attach and update the associated `Parameters` instance using the following methods.
 
 ```php
-$field->addParameter(string $key, mixed $value): static;
-$field->appendParameter(string $key, mixed $value): static;
-$field->prependParameter(string $key, mixed $value): static;
+$field->addParameter(string $name, mixed $value): static;
+$field->appendParameter(string $name, mixed $value): static;
+$field->prependParameter(string $name, mixed $value): static;
 $field->withoutParameters(string ...$keys): static; // this method is deprecated as of version 1.1 use withoutParametersByKeys instead
 $field->withoutAnyParameter(): static;
 $field->withParameters(Parameters $parameters): static;

docs/06-validation.md

@@ -172,7 +172,7 @@ Because parameters are optional by default and the `longitude` parameter is requ
 require its presence. So to fully validate the parameter we need to do the following
 
 ```php
-$member->parameterBykey(
+$member->parameterByName(
     key: 'longitude',
     validate: fn (mixed $value) => match (true) {
         Type::Decimal->supports($value) => true,
@@ -257,9 +257,9 @@ use Bakame\Http\StructuredFields\Validation\ParametersValidator;
 $parametersValidator = ParametersValidator::new()
     ->filterByCriteria(
         fn (Parameters $parameters): bool|string => $parameters
-            ->allowedKeys(['location', 'longitude', 'latitude', 'date'])
+            ->allowedNames(['location', 'longitude', 'latitude', 'date'])
     )
-    ->filterByKeys([
+    ->filterByNames([
         'location' => [
             'validate' => fn (mixed $value) => Type::fromVariable($value)->isOneOf(Type::String, Type::DisplayString),
         ],