Skip to content

Commit 8fdc73c

Browse files
nyamsprodnyamsprod
committed
Simplify public API
1 parent 1ef58b3 commit 8fdc73c

12 files changed

+73
-73
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
4949
- `::hasNoMember` and `::hasMembers` methods have been replaced by `isEmpty` and `isNotEmpty` on containers
5050
- `Dictionary::toPairs` and `Parameters::toPairs`
5151
- `ByteSequence` class replaced by `Bytes` class
52+
- `DataType::create` method use a specific DataType class instead.
5253

5354
## [1.3.0](https://github.com/bakame-php/http-structured-fields/compare/1.2.2...1.3.0) - 2024-01-05
5455

‎docs/01-basic-usage.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ $headerLine = 'picture-in-picture=(), geolocation=(self "https://example.com/"),
2525
$permissions = DataType::Dictionary->parse($headerLine); // parse the field
2626
```
2727

28-
You can now access each permission individually using the following PHP syntax:
28+
The `$permission` variable is a `Dictionary` container instance. you can now access each permission individually
29+
using the container public API:
2930

3031
```php
3132
$permissions['picture-in-picture']->isEmpty(); // returns true because the list is empty
@@ -61,7 +62,7 @@ the RFC.
6162
While field building may look overwhelming, at first, it follows a fully described and tested
6263
process that the package can simplify for you once you read the documentation.
6364

64-
The goal of the example is to show that even without dwelling too much into the ins and out
65+
The goal of the examples are to show that even without dwelling too much into the ins and out
6566
of the package you can easily and quickly parse or serialize compliant fields in PHP.
6667

6768
← [Intro](00-intro.md) | [Parsing and Serializing](02-parsing-serializing.md) →

‎docs/02-parsing-serializing.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,14 @@ package will use the `Dictionary` parsing process to split the field accordingly
2020

2121
```php
2222
use Bakame\Http\StructuredFields\Dictionary;
23+
use Bakame\Http\StructuredFields\DataType;
2324

2425
$headerLine = 'picture-in-picture=(), geolocation=(self "https://example.com/"), camera=*';
26+
27+
$permission = DataType::Dictionary->parse($headerLine);
2528
// can also be written as follows
2629
$permission = Dictionary::fromHttpValue($headerLine);
30+
//both call will return a Dictionary instance on success
2731
```
2832

2933
The `Dictionary` class is an implementation of the structured field `Dictionary` data type. The package
@@ -44,7 +48,7 @@ As example the following existing headers can be classified within the Structure
4448
- The `Accept` headers are `List`
4549
- The `Content-Type` header is an `Item`
4650

47-
These example are taken from a list of [already supported fields](https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html)
51+
These examples are taken from a list of [already supported fields](https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html)
4852

4953
> [!NOTE]
5054
> This means that all the headers listed are already parsable and/or serializable by the package
@@ -54,7 +58,7 @@ the `fromHttpValue` named constructor. This method will parse the field string r
5458
return an instantiated PHP class containing the parsing result. Because there are 2 RFC related
5559
to structured fields, the method accepts an optional enum `Ietf` that indicates which RFC
5660
should be used for conformance. If no enum value is provided, the method will fall back
57-
to using the latest accepted RFC which is at the moment of writing `RFC9651`.
61+
to using the latest accepted RFC at the moment of its release: `RFC9651`.
5862

5963
```php
6064
use Bakame\Http\StructuredFields\OuterList;

‎src/DataType.php

Lines changed: 29 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
namespace Bakame\Http\StructuredFields;
66

7+
use Exception;
78
use Stringable;
89

910
enum DataType: string
@@ -15,25 +16,9 @@ enum DataType: string
1516
case Item = 'item';
1617

1718
/**
18-
* @throws SyntaxError
19+
* @throws SyntaxError|Exception
1920
*/
20-
public function fromRfc9651(Stringable|string $httpValue): OuterList|InnerList|Parameters|Dictionary|Item
21-
{
22-
return $this->parse($httpValue, Ietf::Rfc9651);
23-
}
24-
25-
/**
26-
* @throws SyntaxError
27-
*/
28-
public function fromRfc8941(Stringable|string $httpValue): OuterList|InnerList|Parameters|Dictionary|Item
29-
{
30-
return $this->parse($httpValue, Ietf::Rfc8941);
31-
}
32-
33-
/**
34-
* @throws SyntaxError
35-
*/
36-
public function parse(Stringable|string $httpValue, ?Ietf $rfc = null): OuterList|InnerList|Parameters|Dictionary|Item
21+
public function parse(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): OuterList|InnerList|Parameters|Dictionary|Item
3722
{
3823
return match ($this) {
3924
self::List => OuterList::fromHttpValue($httpValue, $rfc),
@@ -45,40 +30,48 @@ public function parse(Stringable|string $httpValue, ?Ietf $rfc = null): OuterLis
4530
}
4631

4732
/**
48-
* @throws SyntaxError
33+
* @throws SyntaxError|Exception
4934
*/
50-
public function toRfc9651(iterable $data): string
35+
public function serialize(iterable $data, ?Ietf $rfc = Ietf::Rfc9651): string
5136
{
52-
return $this->serialize($data, Ietf::Rfc9651);
37+
return (match ($this) {
38+
self::List => OuterList::fromPairs($data),
39+
self::Dictionary => Dictionary::fromPairs($data),
40+
self::Item => Item::fromPair([...$data]),
41+
self::InnerList => InnerList::fromPair([...$data]),
42+
self::Parameters => Parameters::fromPairs($data),
43+
})->toHttpValue($rfc);
5344
}
5445

5546
/**
56-
* @throws SyntaxError
47+
* @throws SyntaxError|Exception
5748
*/
58-
public function toRfc8941(iterable $data): string
49+
public function fromRfc9651(Stringable|string $httpValue): OuterList|InnerList|Parameters|Dictionary|Item
5950
{
60-
return $this->serialize($data, Ietf::Rfc8941);
51+
return $this->parse($httpValue, Ietf::Rfc9651);
6152
}
6253

6354
/**
64-
* @throws SyntaxError
55+
* @throws SyntaxError|Exception
6556
*/
66-
public function serialize(iterable $data, ?Ietf $rfc = null): string
57+
public function toRfc9651(iterable $data): string
6758
{
68-
return $this->create($data)->toHttpValue($rfc);
59+
return $this->serialize($data, Ietf::Rfc9651);
6960
}
7061

7162
/**
72-
* @throws SyntaxError
63+
* @throws SyntaxError|Exception
7364
*/
74-
public function create(iterable $data): OuterList|InnerList|Parameters|Dictionary|Item
65+
public function fromRfc8941(Stringable|string $httpValue): OuterList|InnerList|Parameters|Dictionary|Item
7566
{
76-
return match ($this) {
77-
self::List => OuterList::fromPairs($data),
78-
self::Dictionary => Dictionary::fromPairs($data),
79-
self::Item => Item::fromPair([...$data]),
80-
self::InnerList => InnerList::fromPair([...$data]),
81-
self::Parameters => Parameters::fromPairs($data),
82-
};
67+
return $this->parse($httpValue, Ietf::Rfc8941);
68+
}
69+
70+
/**
71+
* @throws SyntaxError|Exception
72+
*/
73+
public function toRfc8941(iterable $data): string
74+
{
75+
return $this->serialize($data, Ietf::Rfc8941);
8376
}
8477
}

‎src/Dictionary.php

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
191191
*
192192
* @throws StructuredFieldError|Throwable If the string is not a valid
193193
*/
194-
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
194+
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): self
195195
{
196196
return self::fromPairs(Parser::new($rfc)->parseDictionary($httpValue)); /* @phpstan-ignore-line */
197197
}
@@ -206,7 +206,7 @@ public function toRfc8941(): string
206206
return $this->toHttpValue(Ietf::Rfc8941);
207207
}
208208

209-
public function toHttpValue(?Ietf $rfc = null): string
209+
public function toHttpValue(?Ietf $rfc = Ietf::Rfc9651): string
210210
{
211211
$rfc ??= Ietf::Rfc9651;
212212
$members = [];
@@ -380,7 +380,7 @@ public function hasIndices(int ...$indexes): bool
380380
/**
381381
* Filters and format instance index.
382382
*/
383-
private function filterIndex(int $index, int|null $max = null): int|null
383+
private function filterIndex(int $index, ?int $max = null): ?int
384384
{
385385
$max ??= count($this->members);
386386

‎src/InnerList.php

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ private function filterMember(mixed $member): Item
7272
*
7373
* @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.1
7474
*/
75-
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
75+
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): self
7676
{
7777
return self::fromPair(Parser::new($rfc)->parseInnerList($httpValue));
7878
}
@@ -151,7 +151,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
151151
return self::fromHttpValue($httpValue, Ietf::Rfc8941);
152152
}
153153

154-
public function toHttpValue(?Ietf $rfc = null): string
154+
public function toHttpValue(?Ietf $rfc = Ietf::Rfc9651): string
155155
{
156156
$rfc ??= Ietf::Rfc9651;
157157

@@ -246,7 +246,7 @@ public function hasIndices(int ...$indices): bool
246246
return [] !== $indices;
247247
}
248248

249-
private function filterIndex(int $index, int|null $max = null): int|null
249+
private function filterIndex(int $index, ?int $max = null): ?int
250250
{
251251
$max ??= count($this->members);
252252

@@ -392,8 +392,8 @@ public function removeByIndices(int ...$indices): self
392392
{
393393
$max = count($this->members);
394394
$indices = array_filter(
395-
array_map(fn (int $index): int|null => $this->filterIndex($index, $max), $indices),
396-
fn (int|null $index): bool => null !== $index
395+
array_map(fn (int $index): ?int => $this->filterIndex($index, $max), $indices),
396+
fn (?int $index): bool => null !== $index
397397
);
398398

399399
return match (true) {

‎src/Item.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
4747
*
4848
* @throws SyntaxError If the HTTP value can not be parsed
4949
*/
50-
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
50+
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): self
5151
{
5252
return self::fromPair(Parser::new($rfc)->parseItem($httpValue));
5353
}
@@ -329,7 +329,7 @@ public function type(): Type
329329
*
330330
* @see https://www.rfc-editor.org/rfc/rfc9651.html#section-4.1
331331
*/
332-
public function toHttpValue(?Ietf $rfc = null): string
332+
public function toHttpValue(?Ietf $rfc = Ietf::Rfc9651): string
333333
{
334334
$rfc ??= Ietf::Rfc9651;
335335

‎src/OuterList.php

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ private function filterMember(mixed $member): InnerList|Item
7575
*
7676
* @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.1
7777
*/
78-
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
78+
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): self
7979
{
8080
return self::fromPairs(Parser::new($rfc)->parseList($httpValue)); /* @phpstan-ignore-line */
8181
}
@@ -152,7 +152,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
152152
return self::fromHttpValue($httpValue, Ietf::Rfc8941);
153153
}
154154

155-
public function toHttpValue(?Ietf $rfc = null): string
155+
public function toHttpValue(?Ietf $rfc = Ietf::Rfc9651): string
156156
{
157157
$rfc ??= Ietf::Rfc9651;
158158

@@ -239,7 +239,7 @@ public function hasIndices(int ...$indices): bool
239239
return [] !== $indices;
240240
}
241241

242-
private function filterIndex(int $index, int|null $max = null): int|null
242+
private function filterIndex(int $index, ?int $max = null): ?int
243243
{
244244
$max ??= count($this->members);
245245

@@ -382,8 +382,8 @@ public function removeByIndices(int ...$indices): self
382382
{
383383
$max = count($this->members);
384384
$offsets = array_filter(
385-
array_map(fn (int $index): int|null => $this->filterIndex($index, $max), $indices),
386-
fn (int|null $index): bool => null !== $index
385+
array_map(fn (int $index): ?int => $this->filterIndex($index, $max), $indices),
386+
fn (?int $index): bool => null !== $index
387387
);
388388

389389
return match (true) {

‎src/Parameters.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ public static function fromPairs(StructuredFieldProvider|iterable $pairs): self
134134
*
135135
* @throws SyntaxError|Exception If the string is not a valid
136136
*/
137-
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = null): self
137+
public static function fromHttpValue(Stringable|string $httpValue, ?Ietf $rfc = Ietf::Rfc9651): self
138138
{
139139
return self::fromPairs(Parser::new($rfc)->parseParameters($httpValue)); /* @phpstan-ignore-line */
140140
}
@@ -149,7 +149,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
149149
return self::fromHttpValue($httpValue, Ietf::Rfc8941);
150150
}
151151

152-
public function toHttpValue(?Ietf $rfc = null): string
152+
public function toHttpValue(?Ietf $rfc = Ietf::Rfc9651): string
153153
{
154154
$rfc ??= Ietf::Rfc9651;
155155
$formatter = static fn (Item $member, string $offset): string => match (true) {

‎src/Parser.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ final class Parser
5252
private const FIRST_CHARACTER_RANGE_NUMBER = '-1234567890';
5353
private const FIRST_CHARACTER_RANGE_TOKEN = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ*';
5454

55-
public static function new(?Ietf $rfc = null): self
55+
public static function new(?Ietf $rfc = Ietf::Rfc9651): self
5656
{
5757
return new self($rfc ?? Ietf::Rfc9651);
5858
}

0 commit comments

Comments
 (0)