Skip to content

Commit 9678d25

Browse files
nyamsprodnyamsprod
committed
Adding docblock to document the code
1 parent 3d3869f commit 9678d25

File tree

6 files changed

+187
-0
lines changed

6 files changed

+187
-0
lines changed

‎src/ByteSequence.php

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66

77
final class ByteSequence implements StructuredField
88
{
9+
/**
10+
* Returns a new instance from a Base64 encoded string.
11+
*/
912
public static function fromEncoded(string $encodedValue): self
1013
{
1114
if (1 !== preg_match('/^(?<bytes>[a-z0-9+\/=]*)$/i', $encodedValue, $matches)) {
@@ -18,6 +21,9 @@ public static function fromEncoded(string $encodedValue): self
1821
return new self($decoded);
1922
}
2023

24+
/**
25+
* Returns a new instance from a raw decoded string.
26+
*/
2127
public static function fromDecoded(string $value): self
2228
{
2329
return new self($value);
@@ -27,11 +33,17 @@ private function __construct(private string $value)
2733
{
2834
}
2935

36+
/**
37+
* Returns the decoded string.
38+
*/
3039
public function decoded(): string
3140
{
3241
return $this->value;
3342
}
3443

44+
/**
45+
* Returns the base64 encoded string.
46+
*/
3547
public function encoded(): string
3648
{
3749
return base64_encode($this->value);

‎src/Dictionary.php

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@ private function __construct(
2020
}
2121

2222
/**
23+
* Returns a new instance from an associative iterable construct.
24+
*
25+
* its keys represent the dictionary entry key
26+
* its values represent the dictionary entry value
27+
*
2328
* @param iterable<string, InnerList|Item|ByteSequence|Token|bool|int|float|string> $elements
2429
*/
2530
public static function fromAssociative(iterable $elements = []): self
@@ -33,6 +38,12 @@ public static function fromAssociative(iterable $elements = []): self
3338
}
3439

3540
/**
41+
* Returns a new instance from a pair iterable construct.
42+
*
43+
* Each element is composed of an array with two elements
44+
* the first element represents the instance entry key
45+
* the second element represents the instance entry value
46+
*
3647
* @param iterable<array{0:string, 1:InnerList|Item|ByteSequence|Token|bool|int|float|string}> $pairs
3748
*/
3849
public static function fromPairs(iterable $pairs = []): self
@@ -45,6 +56,11 @@ public static function fromPairs(iterable $pairs = []): self
4556
return $instance;
4657
}
4758

59+
/**
60+
* Returns an instance from an HTTP textual representation.
61+
*
62+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
63+
*/
4864
public static function fromHttpValue(string $httpValue): self
4965
{
5066
$instance = new self();
@@ -71,6 +87,8 @@ public static function fromHttpValue(string $httpValue): self
7187
}
7288

7389
/**
90+
* Extracts a dictionary pair from an HTTP textual representation.
91+
*
7492
* @throws SyntaxError
7593
*
7694
* @return array{0:string, 1:string}
@@ -133,6 +151,8 @@ public function getIterator(): Iterator
133151
}
134152

135153
/**
154+
* Returns an iterable construct of dictionary pairs.
155+
*
136156
* @return Iterator<array{0:string, 1:Item|InnerList}>
137157
*/
138158
public function toPairs(): Iterator
@@ -196,13 +216,19 @@ public function pair(int $index): array
196216
];
197217
}
198218

219+
/**
220+
* Add an element at the end of the instance if the key is new otherwise update the value associated with the key.
221+
*/
199222
public function set(string $key, InnerList|Item|ByteSequence|Token|bool|int|float|string $element): void
200223
{
201224
self::validateKey($key);
202225

203226
$this->elements[$key] = self::filterElement($element);
204227
}
205228

229+
/**
230+
* Validate the instance key against RFC8941 rules.
231+
*/
206232
private static function validateKey(string $key): void
207233
{
208234
if (1 !== preg_match('/^[a-z*][a-z0-9.*_-]*$/', $key)) {
@@ -218,18 +244,27 @@ private static function filterElement(InnerList|Item|ByteSequence|Token|bool|int
218244
};
219245
}
220246

247+
/**
248+
* Delete elements associated with the list of submitted keys.
249+
*/
221250
public function delete(string ...$keys): void
222251
{
223252
foreach ($keys as $key) {
224253
unset($this->elements[$key]);
225254
}
226255
}
227256

257+
/**
258+
* Remove all elements from the instance.
259+
*/
228260
public function clear(): void
229261
{
230262
$this->elements = [];
231263
}
232264

265+
/**
266+
* Add an element at the end of the instance if the key is new delete any previous reference to the key.
267+
*/
233268
public function append(string $key, InnerList|Item|ByteSequence|Token|bool|int|float|string $element): void
234269
{
235270
self::validateKey($key);
@@ -239,6 +274,9 @@ public function append(string $key, InnerList|Item|ByteSequence|Token|bool|int|f
239274
$this->elements[$key] = self::filterElement($element);
240275
}
241276

277+
/**
278+
* Add an element at the beginning of the instance if the key is new delete any previous reference to the key.
279+
*/
242280
public function prepend(string $key, InnerList|Item|ByteSequence|Token|bool|int|float|string $element): void
243281
{
244282
self::validateKey($key);
@@ -248,6 +286,9 @@ public function prepend(string $key, InnerList|Item|ByteSequence|Token|bool|int|
248286
$this->elements = [...[$key => self::filterElement($element)], ...$this->elements];
249287
}
250288

289+
/**
290+
* Merge multiple instances.
291+
*/
251292
public function merge(self ...$others): void
252293
{
253294
foreach ($others as $other) {

‎src/InnerList.php

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@ public static function fromElements(iterable $elements = [], iterable $parameter
3535
return new self(Parameters::fromAssociative($parameters), ...$newElements);
3636
}
3737

38+
/**
39+
* Returns an instance from an HTTP textual representation.
40+
*
41+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1.1
42+
*/
3843
public static function fromHttpValue(string $httpValue): self
3944
{
4045
$field = trim($httpValue);
@@ -143,6 +148,9 @@ public function get(int $index): Item
143148
return $this->elements[$offset];
144149
}
145150

151+
/**
152+
* Insert elements at the beginning of the list.
153+
*/
146154
public function unshift(Item|ByteSequence|Token|bool|int|float|string ...$elements): void
147155
{
148156
$this->elements = [...array_map(self::convertItem(...), $elements), ...$this->elements];
@@ -156,13 +164,21 @@ private static function convertItem(Item|ByteSequence|Token|bool|int|float|strin
156164
};
157165
}
158166

167+
/**
168+
* Insert elements at the end of the list.
169+
*/
159170
public function push(Item|ByteSequence|Token|bool|int|float|string ...$elements): void
160171
{
161172
foreach (array_map(self::convertItem(...), $elements) as $element) {
162173
$this->elements[] = $element;
163174
}
164175
}
165176

177+
/**
178+
* Replace the element associated with the index.
179+
*
180+
* @throws InvalidOffset If the index does not exist
181+
*/
166182
public function insert(int $index, Item|ByteSequence|Token|bool|int|float|string ...$elements): void
167183
{
168184
$offset = $this->filterIndex($index);
@@ -183,6 +199,9 @@ public function replace(int $index, Item|ByteSequence|Token|bool|int|float|strin
183199
$this->elements[$this->filterIndex($index)] = self::convertItem($element);
184200
}
185201

202+
/**
203+
* Delete elements associated with the list of instance indexes.
204+
*/
186205
public function remove(int ...$indexes): void
187206
{
188207
foreach (array_map(fn (int $index): int|null => $this->filterIndex($index), $indexes) as $index) {
@@ -194,11 +213,17 @@ public function remove(int ...$indexes): void
194213
$this->elements = array_values($this->elements);
195214
}
196215

216+
/**
217+
* Remove all elements from the instance.
218+
*/
197219
public function clear(): void
198220
{
199221
$this->elements = [];
200222
}
201223

224+
/**
225+
* Merge multiple instances.
226+
*/
202227
public function merge(self ...$others): void
203228
{
204229
foreach ($others as $other) {

‎src/Item.php

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ private function __construct(
1313
}
1414

1515
/**
16+
* Returns a new instance from a value type and an iterable of key-value parameters.
17+
*
1618
* @param iterable<string,Item|ByteSequence|Token|bool|int|float|string> $parameters
1719
*/
1820
public static function from(
@@ -27,6 +29,11 @@ public static function from(
2729
}, Parameters::fromAssociative($parameters));
2830
}
2931

32+
/**
33+
* Filter a decimal according to RFC8941.
34+
*
35+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.2
36+
*/
3037
public static function filterDecimal(float $value): float
3138
{
3239
if (abs(floor($value)) > 999_999_999_999) {
@@ -36,6 +43,11 @@ public static function filterDecimal(float $value): float
3643
return $value;
3744
}
3845

46+
/**
47+
* Filter a decimal according to RFC8941.
48+
*
49+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.3
50+
*/
3951
public static function filterString(string $value): string
4052
{
4153
if (1 === preg_match('/[^\x20-\x7E]/i', $value)) {
@@ -45,6 +57,11 @@ public static function filterString(string $value): string
4557
return $value;
4658
}
4759

60+
/**
61+
* Filter a decimal according to RFC8941.
62+
*
63+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.1
64+
*/
4865
private static function filterInteger(int $value): int
4966
{
5067
if ($value > 999_999_999_999_999 || $value < -999_999_999_999_999) {
@@ -54,6 +71,12 @@ private static function filterInteger(int $value): int
5471
return $value;
5572
}
5673

74+
/**
75+
* Returns a new instance from an HTTP Header or Trailer value string
76+
* in compliance with RFC8941.
77+
*
78+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3
79+
*/
5780
public static function fromHttpValue(string $httpValue): self
5881
{
5982
$httpValue = trim($httpValue, ' ');
@@ -73,6 +96,8 @@ public static function fromHttpValue(string $httpValue): self
7396
}
7497

7598
/**
99+
* Parses an HTTP textual representation of an Item as a Token Data Type.
100+
*
76101
* @return array{0:Token, 1:string}
77102
*/
78103
private static function parseToken(string $string): array
@@ -93,6 +118,8 @@ private static function parseToken(string $string): array
93118
}
94119

95120
/**
121+
* Parses an HTTP textual representation of an Item as a Boolean Data Type.
122+
*
96123
* @return array{0:bool, 1:string}
97124
*/
98125
private static function parseBoolean(string $string): array
@@ -105,6 +132,8 @@ private static function parseBoolean(string $string): array
105132
}
106133

107134
/**
135+
* Parses an HTTP textual representation of an Item as a Byte Sequence Type.
136+
*
108137
* @return array{0:ByteSequence, 1:string}
109138
*/
110139
private static function parseBytesSequence(string $string): array
@@ -117,6 +146,8 @@ private static function parseBytesSequence(string $string): array
117146
}
118147

119148
/**
149+
* Parses an HTTP textual representation of an Item as a Number Data Type.
150+
*
120151
* @return array{0:int|float, 1:string}
121152
*/
122153
private static function parseNumber(string $string): array
@@ -135,6 +166,8 @@ private static function parseNumber(string $string): array
135166
}
136167

137168
/**
169+
* Parses an HTTP textual representation of an Item as a String Data Type.
170+
*
138171
* @return array{0:string, 1:string}
139172
*/
140173
private static function parseString(string $string): array
@@ -177,6 +210,11 @@ public function toHttpValue(): string
177210
return $this->serializeValue($this->value).$this->parameters->toHttpValue();
178211
}
179212

213+
/**
214+
* Serialize the Item value according to RFC8941.
215+
*
216+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.1
217+
*/
180218
private function serializeValue(Token|ByteSequence|int|float|string|bool $value): string
181219
{
182220
return match (true) {
@@ -189,6 +227,11 @@ private function serializeValue(Token|ByteSequence|int|float|string|bool $value)
189227
};
190228
}
191229

230+
/**
231+
* Serialize the Item decimal value according to RFC8941.
232+
*
233+
* @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.1.5
234+
*/
192235
private function serializeDecimal(float $value): string
193236
{
194237
/** @var string $result */

0 commit comments

Comments
 (0)