Improve documentation v2

Author: nyamsprod

docs/00-intro.md

@@ -23,9 +23,9 @@ $container[1]->parameterByName(name: 'q', default: 1.0); // returns 1.0 if the p
 
 While they are plenty of HTTP headers and trailers, they have historically come each with their own set of 
 rules and constraints when it came to parsing and serializing them. Trying to use the parsing logic of a cookie header
-to parse an accept header will fail. The various parsing logics hinders HTTP headers and trailers usage, modernization
-or security. The [Structured Field RFC](https://www.rfc-editor.org/rfc/rfc9651.html) aim at tackling those issues by
-unifying HTTP headers and trailers parsing and serializing.
+to parse an accept header will fail. The various parsing logics hinder HTTP headers and trailers usage, modernization
+or security. The [Structured Field RFC](https://www.rfc-editor.org/rfc/rfc9651.html) aim at tackling those issues by unifying HTTP headers and trailers
+parsing and serializing.
 
 New HTTP headers or trailers (called HTTP fields) are encouraged to use the RFC algorithm, data and value types and
 ongoing discussions are happening to [retrofit existing headers that do not match the RFC](https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html) into new 
@@ -37,7 +37,7 @@ shapes that would be compatible with it.
 > While this package parses and serializes HTTP field value, it does not validate its content
 > against any conformance rule out of the box. You are still required to perform such a
 > compliance check against the constraints of the corresponding field. While Content
-> validation is still possible and higly encouraged when using this library. Because
+> validation is still possible and highly encouraged when using this library. Because
 > of the wide variety of HTTP fields it can not be made mandatory.
 
 ## System Requirements
@@ -49,7 +49,7 @@ shapes that would be compatible with it.
 Use composer:
 
 ```
-composer require bakame/http-structured-fields
+composer require bakame/http-structured-fields:^2.0
 ```
 
 ## Using the package

docs/01-basic-usage.md

@@ -8,7 +8,7 @@ order: 2
 ## Parsing the Field
 
 The first way to use the package is to enable HTTP header or HTTP trailer parsing. We will refer to them
-as fields for the rest of the documentation as it is how they are named in the IETF RFC.
+as HTTP fields for the rest of the documentation as it is how they are named in the IETF RFC.
 
 Let's say we want to parse the [Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#syntax) field. The first thing to know
 is that each structured field is defined against one specific data type which is
@@ -37,8 +37,7 @@ $permissions->isEmpty();                       // returns false the dictionary c
 ```
 
 > [!WARNING]
-> If parsing fails a `SyntaxError` exception is thrown with the information about why the conversion
-> could not be achieved.
+> If parsing fails a `SyntaxError` exception is thrown with the information about why it failed.
 
 ## Creating a new field
 
@@ -54,11 +53,14 @@ echo DataType::Dictionary->serialize([
 // returns picture-in-picture=(), geolocation=(self "https://example.com/"), camera=*
 ```
 
-Again, we start from the knowledge that the field is a `Dictionary`, and by default content is added using
-tuple or pairs. As such we can turn the iterable construct we have into a proper HTTP field text 
-representation by applying the serialization mechanism described in the RFC. While field building
-may look overwhelming, at first, it follows a fully described and tested process that the package
-can simplify for you once you read the documentation.
+Again, we start from the knowledge that the field is a `Dictionary`, content is added using
+pairs to respect value position. As such we can turn the iterable construct we have into a
+proper HTTP field text representation by applying the serialization mechanism described in
+the RFC.
+
+While field building may look overwhelming, at first, it follows a fully described and tested
+process that the package can simplify for you once you read the documentation.
+
 The goal of the example is to show that even without dwelling too much into the ins and out
 of the package you can easily and quickly parse or serialize compliant fields in PHP.
 

docs/02-parsing-serializing.md

@@ -47,7 +47,7 @@ As example the following existing headers can be classified within the Structure
 These example are taken from a list of [already supported fields](https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html)
 
 > [!NOTE]
-> This means that those headers are already supported when parsing or serializing them by the package
+> This means that all the headers listed are already parsable and/or serializable by the package
 
 All the classes share the same methods for parsing the HTTP text representation of the field. They all use
 the `fromHttpValue` named constructor. This method will parse the field string representation and
@@ -97,7 +97,7 @@ construct can be summarized as follows:
 - `InnerList`and `Parameters` instances can only contain `Item`;
 - `OuterList` and `InnerList` members can only be accessed by their indices (ie: they are list);
 - `Dictionary` and `Parameters` members can also be accessed by their name (ie: they are ordered map);
-- `Item` and `InnerList` instancs can have a `Parameters` container attached to.
+- `Item` and `InnerList` instances can have a `Parameters` container attached to them.
 - `Item` contain in a `Parameters` container **can not have** parameters attached to them to avoid recursion. They are named **Bare Item**.
 - `Item` contain in a `InnerList` container **can have** parameters attached to them.
 
@@ -142,8 +142,8 @@ $field[0]->parameterByName('q'); // returns null
 Each Data type implementation is able to convert itself into a proper HTTP text representation
 using its `toHttpValue` method. The method is complementary to the `fromHttpValue` named constructor
 in that it does the opposite of that method. Just like the `fromHttpValue`, it can take an optional
-`Ietf` enum to specifu which RFC version it should adhere to for serialization. And two syntactic
-methods `toRfc9651` and `toRfc8941` are also present to ease usage. Last but not least All classes
+`Ietf` enum to specify which RFC version it should adhere to for serialization. And two syntactic
+methods `toRfc9651` and `toRfc8941` are also present to ease usage. Last but not least, all classes
 implements the `Stringable` interface using the latest accepted RFC.
 
 ```php
@@ -158,7 +158,7 @@ $field->toHttpValue();
 The `toHttpValue` method applies by default all the normalizations recommended by the RFC. 
 
 > [!TIP]
-> This is the mechanism used by the `DataType::serialize` method. Once the Structured
-> field has been created, the method calls its `toHttpValue` method.
+> This is the mechanism used by the `DataType::serialize` method. Once the HTTP Structured
+> Field has been created, the method calls its `toHttpValue` method.
 
 ← [Basic Usage](01-basic-usage.md)  |  [Accessing Field Values](03-field-values.md) →

docs/03-field-values.md

@@ -54,7 +54,7 @@ echo Type::tryFromVariable(new SplTempFileObject()); // returns null
 ```
 
 To ease validation the `Type::equals`  and `Type::isOneOf` methods are added to check if
-the variable is of expected type. It can also be used to compare types.
+the variable is one of the expected type. It can also be used to compare types.
 
 ```php
 use Bakame\Http\StructuredFields\Type;
@@ -149,9 +149,9 @@ use Bakame\Http\StructuredFields\Token;
 Item:new(DateTimeInterface|Byte|Token|DisplayString|string|int|array|float|bool $value): self
 Item:tryNew(mixed $value): ?self
 Item::fromDecodedBytes(Stringable|string $value): self;
+Item::fromEncodedBytes(Stringable|string $value): self;
 Item::fromEncodedDisplayString(Stringable|string $value): self;
 Item::fromDecodedDisplayString(Stringable|string $value): self;
-Item::fromEncodedBytes(Stringable|string $value): self;
 Item::fromToken(Stringable|string $value): self;
 Item::fromString(Stringable|string $value): self;
 Item::fromDate(DateTimeInterface $datetime): self;
@@ -169,14 +169,14 @@ To update the `Item` instance value, use the `withValue` method:
 ```php
 use Bakame\Http\StructuredFields\Item;
 
-Item::withValue(DateTimeInterface|Byte|Token|DisplayString|string|int|float|bool $value): static
+Item::withValue(DateTimeInterface|Byte|Token|DisplayString|string|int|float|bool $value): self
 ```
 
 ### Item Parameters
 
-Items can have parameters attached to them. A parameter is a bere item, an item which can not have parameters
+Items can have parameters attached to them. A parameter is a **bare item**, an item which can not have parameters
 attach to it, to avoid recursive behaviour. Parameters are grouped in an ordered map container called `Parameters`.
-They can be accessed by their indices **but also** by their required key attached to them.
+They can be accessed by their indices **but also** by their **required key** attached to them.
 
 ```php
 
@@ -193,7 +193,7 @@ By default, you can access the member `Item` of a parameters using the following
 - `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
-will be explored in the next section about the containers.
+It is possible to alter and modify the `Parameters` attached to an `Item` but this will be explored in
+the next section about the containers.
 
 ← [Parsing and Serializing](02-parsing-serializing.md)  |  [Containers](04-containers.md) →

docs/04-containers.md

@@ -5,7 +5,7 @@ order: 5
 
 # Working with Structured Fields Containers
 
-While building or updating a Bare Item is straightforward, doing the same with the structured field containers
+While building or updating a Bare Item is straightforward, doing the same with structured field containers
 requires a bit more logic. In the following sections we will explore how we can access, build and update
 containers.
 
@@ -65,7 +65,7 @@ unset($permissions['a']); // triggers a ForbiddenOperation exception
 > 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 name:
+The `Dictionary` and `Parameters` classes also allow accessing their members as value using their name:
 
 ```php
 $permissions->hasName('picture-in-picture');           // returns true
@@ -87,13 +87,13 @@ $permissions->indexByName('geolocation'): // returns 1
 > 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` with `OuterList` and `InnerList`.
-> The `ArrayAccess` interface proxy the result from `getByName`  with `Dictionary` and `Parameters`.
+> 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`.
 
 ### 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`.
+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
@@ -103,7 +103,7 @@ parameter.
 > The `parameterByName` proxy the result from `valueByName`.
 > The `parameterByIndex` proxy the result from `valueByIndex`.
 
-## Building and Updating COntainers
+## Building and Updating Containers
 
 Every container can be used as a builder to create an HTTP field value. Because we are
 using immutable value objects any change to the value object will return a new instance
@@ -438,4 +438,18 @@ echo InnerList::new('foo', 'bar')
 // ("foo" "bar");expire=@1681538756;path="/";max-age=2500
 ```
 
+Last but not least, all datatypes exposes the conditional `when` method to improve building the structured field.
+This can be helpful if fdr instance your input value would otherwise trigger an exception.
+
+In the example below we are conditionally building the an `Item` depending on the data found in the
+`$cache` value object. This is also possible for all containers.
+
+```php
+Item::new($cache->name)
+    ->when($cache->hit, fn (Item $item) => $item->appendParameter('hit', $cacher->hit))
+    ->when(null !== $cache->ttl, fn (Item $item) => $item->appendParameter('ttl', $cache->ttl)) 
+    ->when(null !== $cache->key, fn (Item $item) => $item->appendParameter('key', $cache->key)) 
+    ->when(null !== $cache->detail, fn (Item $item) => $item->appendParameter('detail', $cache->detail));
+```
+
 ← [Accessing Field Values](03-field-values.md)  |  [Validation](05-validation) →