Improve Token API

Author: nyamsprod

CHANGELOG.md

@@ -12,6 +12,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `Item` implements the `ValueAccess` interface;
 - `Item::toPair` to complement `Item::fromPair`;
 - `Value` internal class to improve Item public API;
+- `Token::toString` to return the string representation of the token.
 - Adding support for `MapKey` object to access container members.
 
 ### Fixed
@@ -27,6 +28,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[BC Break]** `InnerList::fromPairParameters` use `InnerList::fromPairs` instead.
 - **[BC Break]** `InnerList::fromAssociativeParameters` use `InnerList::fromAssociative` instead.
 - **[BC Break]** `Value` interface use a combination of `ValueAccess` **and** `ParameterAccess` instead.
+- **[BC Break]** `Token::value` is no longer public use `Token::toString` instead.
 
 ## [0.8.0] - 2023-03-12
 

README.md

@@ -114,15 +114,15 @@ ByteSequence::fromDecoded(string|Stringable $value): ByteSequence;
 ByteSequence::fromEncoded(string|Stringable $value): ByteSequence;
 ```
 
-Both class are final and immutable and their value can not be modified once instantiated.
+Both classes are final and immutable; their value can not be modified once instantiated.
 To access their value, they expose the following API:
 
 ```php
 use Bakame\Http\StructuredFields\Token;
 use Bakame\Http\StructuredFields\ByteSequence;
 
 $token = Token::fromString('application/text+xml');
-echo $token->value; // returns 'application/text+xml'
+echo $token->toString(); // returns 'application/text+xml'
 
 $byte = ByteSequence::fromDecoded('Hello world!');
 $byte->decoded(); // returns 'Hello world!'
@@ -150,17 +150,7 @@ $item = Item::from(CarbonImmutable::parse('today'));
 $item->type();  // return Type::Date;
 $item->value()  // return CarbonImmutable::parse('today') (because it extends DateTimeImmutable)
 // you can also do 
-Type::Date->equals($item->type()); // returns true
-```
-
-You can also read the associated `Parameters` instance attached to an `Item` instance
-using the following methods:
-
-```php
-use Bakame\Http\StructuredFields\Parameters;
-
-$item->parameter($key): ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool|null;
-$item->parameters(): Parameters;
+Type::Date->equals($item); // returns true
 ```
 
 #### Containers
@@ -199,7 +189,9 @@ $container->pair(int $offset): array{0:string, 1:StructuredField};
 $container->toPairs(): iterable<array{0:string, 1:StructuredField}>;
 ```
 
-You can also read the associated `Parameters` instance attached to an `InnerList` instance
+#### Accessing the paramters values
+
+You can also read the associated `Parameters` instance attached to an `InnerList` or a `Item` instances
 using the following methods:
 
 ```php
@@ -219,21 +211,6 @@ The `Item` value object exposes lots of named constructors.
 use Bakame\Http\StructuredFields\ByteSequence;
 use Bakame\Http\StructuredFields\Item;
 
-$item = Item::fromPair(["hello world", [
-    ["a", Item::from(ByteSequence::fromDecoded("Hello World"))],
-]]);
-$item->value();            // returns "hello world"
-$item->type();             // returns Type::String
-$item->parameter("a");    // returns ByteSequence::fromDecoded('Hello World');
-echo $item->toHttpValue(); // returns "hello world";a=:SGVsbG8gV29ybGQ=:
-```
-
-Once again it is possible to simplify this code using the following technique:
-
-```php
-use Bakame\Http\StructuredFields\ByteSequence;
-use Bakame\Http\StructuredFields\Item;
-
 $item = Item::from("hello world", [
     "a" => Item::fromDecodedByteSequence("Hello World")
 ]);
@@ -261,10 +238,6 @@ The `Item::from` method expects an associative iterable to represents the parame
 ```php
 use Bakame\Http\StructuredFields\Item;
 
-//@type SfItemInput ByteSequence|Token|DateTimeInterface|Stringable|string|int|float|bool
-
-Item::from(SfItemInput $value, iterable<string, SfItemInput> $associativeParameters = []): self;
-Item::fromPair(array{0:SfItemInput, 1:iterable<array{0:string, 1:SfItemInput}>} $pair): self;
 Item::fromDecodedByteSequence(string $value): self;
 Item::fromEncodedByteSequence(string $value): self;
 Item::fromToken(string $value): self;
@@ -286,21 +259,6 @@ use Bakame\Http\StructuredFields\Parameters;
 Item::withValue(SfItemInput $value): static
 ```
 
-And just like with the `InnerList` instance the `Item` object provides additional modifying methods
-to help deal with parameters. You can attach and update the associated `Parameters` instance using the
-following methods:
-
-```php
-use Bakame\Http\StructuredFields\Parameters;
-
-$item->addParameter($key, $value): static;
-$item->appendParameter($key, $value): static;
-$item->prependParameter($key, $value): static;
-$item->withoutParameters(...$keys): static;
-$item->withoutAnyParameter(): static;
-$item->withParameters(Parameters $parameters): static;
-```
-
 The `Dictionary` and `Parameters` instances can be build with an associative iterable structure as shown below
 
 ```php
@@ -405,28 +363,65 @@ $list->replace($key, $member): static;
 $list->remove(...$key): static;
 ```
 
-On `InnerList` instances it is possible to attach and update a `Parameters` instance using the
-following methods:
+# Adding and updating parameters
+
+Apart from the `Item::from` named constructor, you can initialize a new Item instance using pairs
+as defined in the RFC:
 
 ```php
-$list->addParameter($key, $value): static;
-$list->appendParameter($key, $value): static;
-$list->prependParameter($key, $value): static;
-$list->withoutParameters(...$keys): static;
-$list->withoutAnyParameter(): static;
-$list->withParameters(Parameters $parameters): static;
+use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Item;
+
+$item = Item::fromPair(["hello world", [
+    ["a", Item::from(ByteSequence::fromDecoded("Hello World"))],
+]]);
+$item->value();            // returns "hello world"
+$item->type();             // returns Type::String
+$item->parameter("a");    // returns ByteSequence::fromDecoded('Hello World');
+echo $item->toHttpValue(); // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
 It is also possible to instantiate an `InnerList` instance with included parameters
 using one of those two additional named constructors:
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
+use Bakame\Http\StructuredFields\Item;
+
+//@type SfItemInput ByteSequence|Token|DateTimeInterface|Stringable|string|int|float|bool
+
+Item::from(SfItemInput $value, iterable<string, SfItemInput> $parameters = []): self;
+Item::fromPair(array{0:SfItemInput, 1:iterable<array{0:string, 1:SfItemInput}>} $pair): self;
 
 InnerList::fromAssociative(iterable<string, SfItemInput> $parameters, ...$members): self;
 InnerList::fromPair(array{0:list<Item>, iterable<array{0:string, 1:SfItemInput}>} $pair): self;
 ```
 
+Both classes allow return their respective pair representation via the `toPair` method.
+
+```php
+use Bakame\Http\StructuredFields\InnerList;
+use Bakame\Http\StructuredFields\Item;
+use Bakame\Http\StructuredFields\Parameters;
+
+InnerList::toPair(): array{0:list<Item>, 1:Parameters}>};
+Item::toPair(): array{0:mixed, 1:Parameters}>};
+```
+
+The `InnerList` and  `Item` object provide additional modifying methods to help deal with parameters.
+You can attach and update the associated `Parameters` instance using the following methods:
+
+```php
+use Bakame\Http\StructuredFields\Parameters;
+
+$field->addParameter(string $key, mixed $value): static;
+$field->appendParameter(string $key, mixed $value): static;
+$field->prependParameter(string $key, mixed $value): static;
+$field->withoutParameters(string ...$keys): static;
+$field->withoutAnyParameter(): static;
+$field->withParameters(Parameters $parameters): static;
+```
+
 ## Contributing
 
 Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](.github/CONTRIBUTING.md) and [CODE OF CONDUCT](.github/CODE_OF_CONDUCT.md) for details.

src/Token.php

@@ -12,13 +12,18 @@
  */
 final class Token
 {
-    private function __construct(public readonly string $value)
+    private function __construct(private readonly string $value)
     {
         if (1 !== preg_match("/^([a-z*][a-z\d:\/!#\$%&'*+\-.^_`|~]*)$/i", $this->value)) {
             throw new SyntaxError('Invalid characters in token.');
         }
     }
 
+    public function toString(): string
+    {
+        return $this->value;
+    }
+
     public static function fromString(Stringable|string $value): self
     {
         return new self((string) $value);

src/Value.php

@@ -194,7 +194,7 @@ public function serialize(): string
             is_int($this->value) => (string) $this->value,
             is_float($this->value) => self::serializeDecimal($this->value),
             is_bool($this->value) => '?'.($this->value ? '1' : '0'),
-            $this->value instanceof Token => $this->value->value,
+            $this->value instanceof Token => $this->value->toString(),
             $this->value instanceof DateTimeImmutable => '@'.$this->value->getTimestamp(),
             default => ':'.$this->value->encoded().':',
         };