@@ -18,11 +18,12 @@ The package can be used to:
18
18
19
19
- parse and serialize HTTP Structured Fields
20
20
- build or update HTTP Structured Fields in a predicable way;
21
+ - access HTTP Structured Fields data
21
22
22
23
``` php
23
24
use Bakame\Http\StructuredFields;
24
25
25
- $field = StructuredFields\Item::from("/terms", ['rel' => " copyright" , 'anchor' => '#foo']);
26
+ $field = StructuredFields\Item::from("/terms", ['rel' => ' copyright' , 'anchor' => '#foo']);
26
27
echo $field->toHttpValue(); //display "/terms";rel="copyright";anchor="#foo"
27
28
echo $field->value; //display "/terms"
28
29
echo $field->parameters->value('rel'); //display "copyright"
@@ -42,18 +43,32 @@ Using composer:
42
43
composer require bakame/http-structured-fields
43
44
```
44
45
46
+ or download the library and:
47
+
48
+ - use any other [ PSR-4] [ 4 ] compatible autoloader.
49
+ - use the bundle autoloader script as shown below:
50
+
51
+ ~~~ php
52
+ require 'path/to/http-structured-fields/repo/autoload.php';
53
+
54
+ use Bakame\Http\StructuredFields;
55
+
56
+ $list = StructuredFields\OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
57
+ echo $list->get(-1)->value; //returns '/member/*/comments'
58
+ ~~~
59
+
45
60
Documentation
46
61
---
47
62
48
- ## Parsing and Serializing Structured Fields
63
+ ### Parsing and Serializing Structured Fields
49
64
50
- There are three top-level types that an HTTP field can be defined as:
65
+ an HTTP field can be defined as:
51
66
52
- - Dictionaries ,
53
- - Lists ,
54
- - and Items .
67
+ - a Dictionary ,
68
+ - a List ,
69
+ - an Item .
55
70
56
- For each of those top-level types, the package provide a dedicated value object to parse the textual
71
+ For each of those top-level types, the package provides a dedicated value object to parse the textual
57
72
representation of the field and to serialize the value object back to the textual representation.
58
73
59
74
- Parsing is done via a common named constructor ` fromHttpValue ` which expects the Header or Trailer string value.
@@ -72,19 +87,14 @@ $item = StructuredFields\Item::fromHttpValue('"foo";a=1;b=2"');
72
87
echo $item->toHttpValue(); // "foo";a=1;b=2
73
88
```
74
89
75
- ## Building Structured Fields
76
-
77
- The RFC defines different data types to handle structured fields values.
78
-
79
- ### Items
90
+ ### Building Structured Fields
80
91
81
- Items are the minimal building block for structured fields. The following section explains
82
- how to build and interact with them.
92
+ #### Items
83
93
84
- #### Bare Items
94
+ ##### Bare Items
85
95
86
96
Items can have different types [ defined in the RFC] [ 3 ] . They are translated to PHP native type
87
- when possible. Two additional classes
97
+ when possible otherwise two additional classes
88
98
89
99
- ` Bakame\Http\StructuredFields\Token ` and
90
100
- ` Bakame\Http\StructuredFields\ByteSequence `
@@ -100,12 +110,12 @@ are used to represent non-native types as shown in the table below:
100
110
| Token | class ` Token ` | ` Item::isToken ` |
101
111
| Byte Sequence | class ` ByteSequence ` | ` Item::isByteSequence ` |
102
112
103
- #### Extended Items
113
+ ##### Items associated with parameters
104
114
105
- Item can be associated with ` Parameters ` that are ordered maps of key-value pairs, where the
106
- keys is a string and the value are bare items. Their public API will be cover in subsequent paragraphs.
115
+ Item can be associated with that an ordered maps of key-value pairs called ` Parameters ` , where the
116
+ keys are strings and the value are bare items. Their public API will be cover in subsequent paragraphs.
107
117
108
- #### Usage
118
+ ##### Building and accessing Items data
109
119
110
120
Instantiation via type recognition is done using the ` Item::from ` named constructor.
111
121
@@ -157,10 +167,10 @@ $item->isDecimal(); //return false
157
167
$item->isInteger(); //return true
158
168
```
159
169
160
- ### Containers
170
+ #### Containers
161
171
162
- Apart from the ` Item ` , the RFC defines different items containers with different requirements. The
163
- package exposes those containers via the following value objects:
172
+ Apart from the ` Item ` structure , the package exposes different containers
173
+ with different requirements via the following value objects:
164
174
165
175
- ` Dictionary ` ,
166
176
- ` Parameters ` ,
@@ -170,25 +180,37 @@ package exposes those containers via the following value objects:
170
180
At any given time it is possible with each of these objects to:
171
181
172
182
- iterate over its members using the ` IteratorAggregate ` interface;
183
+ - know the number of members it contains via the ` Countable ` interface;
173
184
- tell whether the container is empty via an ` isEmpty ` method;
174
- - know the number of members contained in the container via the ` Countable ` interface;
175
- - clear the container using the ` clear ` method;
185
+ - clear its content using the ` clear ` method;
186
+
187
+ ** Of note:**
188
+
189
+ - All setter methods are chainable
190
+ - For setter methods, Item types are inferred using ` Item::from ` if a ` Item ` object is not submitted.
191
+ - Because all containers can be access by their indexes, some changes may re-index them as to not expose missing indexes.
176
192
177
193
``` php
178
194
use Bakame\Http\StructuredFields;
179
195
180
196
$parameters = StructuredFields\Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
181
- count($parameters); // return 3
182
- $parameters->isEmpty(); // returns false
183
- $parameters->toHttpValue(); // return ';a=1;b=2;c="hello world"'
197
+ count($parameters); // returns 3
198
+ $parameters->isEmpty(); // returns false
199
+ $parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'
200
+ $parameters->clear()->isEmpty(); // returns true
184
201
```
185
202
186
- #### Ordered Maps
203
+ ##### Ordered Maps
187
204
188
205
The ` Parameters ` and the ` Dictionary ` classes allow associating a string
189
- key to its members as such they expose
206
+ key to its members
207
+
208
+ - ` Parameters ` can only contains ` Item ` instances
209
+ - ` Dictionary ` instance can contain ` Item ` and/or ` InnerList ` instances.
190
210
191
- the following getter methods:
211
+ Both classes exposes the following:
212
+
213
+ getter methods:
192
214
193
215
- ` fromAssociative ` a named constructor to instantiate the container with an associative array;
194
216
- ` fromPairs ` a named constructor to instantiate the container with a list of key-value pairs;
@@ -199,7 +221,7 @@ the following getter methods:
199
221
- ` get ` returns the element associated to a specific ` key ` ;
200
222
- ` pair ` returns the key-pair association present at a specific ` index ` (negative indexes are supported);
201
223
202
- the following setter methods:
224
+ setter methods:
203
225
204
226
- ` set ` add an element at the end of the container if the key is new otherwise only the value is updated;
205
227
- ` append ` always add an element at the end of the container, if already present the previous value is removed;
@@ -208,8 +230,6 @@ the following setter methods:
208
230
- ` mergeAssociative ` merge multiple instances of iterable structure as associative constructs;
209
231
- ` mergePairs ` merge multiple instances of iterable structure as pairs constructs;
210
232
211
- ** All setter methods are chainable.**
212
-
213
233
``` php
214
234
use Bakame\Http\StructuredFields;
215
235
@@ -230,11 +250,6 @@ echo $dictionary
230
250
->toHttpValue(); //returns "a=?0, z=42.0"
231
251
```
232
252
233
- ** Item types are inferred using ` Item::from ` if a ` Item ` object is not submitted.**
234
-
235
- - ` Parameters ` can only contains ` Item ` instances
236
- - ` Dictionary ` instance can contain ` Item ` and ` InnerList ` instances.
237
-
238
253
The ` Parameters ` instance exposes the following additional methods:
239
254
240
255
- ` Parameters::values() ` to list all existing Bare Items value as an array list;
@@ -259,10 +274,17 @@ $parameters->toHttpValue(); // returns ;b="false";foo="foo"
259
274
$parameters->value('unknown'); // returns null
260
275
```
261
276
262
- #### Lists
277
+ ##### Lists
278
+
279
+ The ` OrderedList ` and the ` InnerList ` classes are list of members that act as containers
280
+
281
+ The main distinction between ` InnerList ` and ` OrderedList ` are:
282
+
283
+ - ` OrderedList ` members must be ` InnerList ` or ` Items ` ;
284
+ - ` InnerList ` members must be ` Items ` ;
285
+ - ` InnerList ` can have a ` Parameters ` instance attached to it;
263
286
264
- The ` OrderedList ` and the ` InnerList ` classes are list of members
265
- that act as containers and also expose the following
287
+ Both classes exposes the following:
266
288
267
289
getter methods:
268
290
@@ -271,20 +293,14 @@ getter methods:
271
293
- ` get ` to access an element at a given index (negative indexes are supported)
272
294
- ` has ` tell whether an element is attached to the container using its ` index ` ;
273
295
274
- setter methods ( ** All setter methods are chainable. ** )
296
+ setter methods
275
297
276
298
- ` push ` to add elements at the end of the list;
277
299
- ` unshift ` to add elements at the beginning of the list;
278
300
- ` insert ` to add elements at a given position in the list;
279
301
- ` replace ` to replace an element at a given position in the list;
280
302
- ` remove ` to remove elements based on their position;
281
303
282
- to enable manipulation their content.
283
-
284
- ** Item types are inferred using ` Item::from ` if a ` Item ` object is not submitted.**
285
-
286
- ** EVERY CHANGE IN THE LIST WILL RE-INDEX THE LIST AS TO NOT EXPOSE MISSING INDEXES**
287
-
288
304
``` php
289
305
use Bakame\Http\StructuredFields;
290
306
@@ -302,18 +318,13 @@ $orderedList = StructuredFields\OrderedList::from(
302
318
echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
303
319
```
304
320
305
- The distinction between ` InnerList ` and ` OrderedList ` is well explained in the
306
- RFC but the main ones are:
307
-
308
- - ` InnerList ` members must be ` Items ` ;
309
- - ` OrderedList ` members must be ` InnerList ` or ` Items ` ;
310
- - ` InnerList ` has a ` Parameters ` instance attached to it that you can access via its readonly property ` parameters ` , not ` OrderedList ` ;
321
+ A ` Parameters ` instance can be associated to an ` InnerList ` using the same API described for the ` Item ` value object.
311
322
312
323
``` php
313
324
use Bakame\Http\StructuredFields;
314
325
315
326
$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
316
- $innerList->parameters; //returns a StructuredFields\Parameters object
327
+ $innerList->parameters; //returns a StructuredFields\Parameters object
317
328
$innerList->parameters->value('a'); // returns true
318
329
```
319
330
@@ -352,7 +363,7 @@ Credits
352
363
Attribution
353
364
-------
354
365
355
- This package is heavily inspired by previous work done by [ Gapple] ( https://twitter.com/gappleca ) on [ Structured Field Values for PHP] ( https://github.com/gapple/structured-fields/ ) .
366
+ The package internal parser is heavily inspired by previous work done by [ Gapple] ( https://twitter.com/gappleca ) on [ Structured Field Values for PHP] ( https://github.com/gapple/structured-fields/ ) .
356
367
357
368
License
358
369
-------
@@ -362,3 +373,4 @@ The MIT License (MIT). Please see [License File](LICENSE) for more information.
362
373
[ 1 ] : https://www.rfc-editor.org/rfc/rfc8941.html
363
374
[ 2 ] : https://www.ietf.org/id/draft-ietf-httpbis-retrofit-00.html
364
375
[ 3 ] : https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3
376
+ [ 4 ] : https://www.php-fig.org/psr/psr-4/
0 commit comments