Skip to content

Commit c8ec5c8

Browse files
committed
Update README documentation
1 parent 266f157 commit c8ec5c8

File tree

2 files changed

+73
-57
lines changed

2 files changed

+73
-57
lines changed

Makefile

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,8 @@ phpcs:
2222
test:
2323
@docker run --rm -it -v$(PWD):/app composer test
2424

25+
# test
26+
sandbox:
27+
@docker run --rm -it -v$(PWD):/app php:8.1-cli-alpine php ./app/test.php
28+
2529
.PHONY: install update phpunit phpstan phpcs test

README.md

Lines changed: 69 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,12 @@ The package can be used to:
1818

1919
- parse and serialize HTTP Structured Fields
2020
- build or update HTTP Structured Fields in a predicable way;
21+
- access HTTP Structured Fields data
2122

2223
```php
2324
use Bakame\Http\StructuredFields;
2425

25-
$field = StructuredFields\Item::from("/terms", ['rel' => "copyright", 'anchor' => '#foo']);
26+
$field = StructuredFields\Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
2627
echo $field->toHttpValue(); //display "/terms";rel="copyright";anchor="#foo"
2728
echo $field->value; //display "/terms"
2829
echo $field->parameters->value('rel'); //display "copyright"
@@ -42,18 +43,32 @@ Using composer:
4243
composer require bakame/http-structured-fields
4344
```
4445

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+
4560
Documentation
4661
---
4762

48-
## Parsing and Serializing Structured Fields
63+
### Parsing and Serializing Structured Fields
4964

50-
There are three top-level types that an HTTP field can be defined as:
65+
an HTTP field can be defined as:
5166

52-
- Dictionaries,
53-
- Lists,
54-
- and Items.
67+
- a Dictionary,
68+
- a List,
69+
- an Item.
5570

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
5772
representation of the field and to serialize the value object back to the textual representation.
5873

5974
- 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"');
7287
echo $item->toHttpValue(); // "foo";a=1;b=2
7388
```
7489

75-
## Building Structured Fields
76-
77-
The RFC defines different data types to handle structured fields values.
78-
79-
### Items
90+
### Building Structured Fields
8091

81-
Items are the minimal building block for structured fields. The following section explains
82-
how to build and interact with them.
92+
#### Items
8393

84-
#### Bare Items
94+
##### Bare Items
8595

8696
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
8898

8999
- `Bakame\Http\StructuredFields\Token` and
90100
- `Bakame\Http\StructuredFields\ByteSequence`
@@ -100,12 +110,12 @@ are used to represent non-native types as shown in the table below:
100110
| Token | class `Token` | `Item::isToken` |
101111
| Byte Sequence | class `ByteSequence` | `Item::isByteSequence` |
102112

103-
#### Extended Items
113+
##### Items associated with parameters
104114

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.
107117

108-
#### Usage
118+
##### Building and accessing Items data
109119

110120
Instantiation via type recognition is done using the `Item::from` named constructor.
111121

@@ -157,10 +167,10 @@ $item->isDecimal(); //return false
157167
$item->isInteger(); //return true
158168
```
159169

160-
### Containers
170+
#### Containers
161171

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:
164174

165175
- `Dictionary`,
166176
- `Parameters`,
@@ -170,25 +180,37 @@ package exposes those containers via the following value objects:
170180
At any given time it is possible with each of these objects to:
171181

172182
- iterate over its members using the `IteratorAggregate` interface;
183+
- know the number of members it contains via the `Countable` interface;
173184
- 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.
176192

177193
```php
178194
use Bakame\Http\StructuredFields;
179195

180196
$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
184201
```
185202

186-
#### Ordered Maps
203+
##### Ordered Maps
187204

188205
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.
190210

191-
the following getter methods:
211+
Both classes exposes the following:
212+
213+
getter methods:
192214

193215
- `fromAssociative` a named constructor to instantiate the container with an associative array;
194216
- `fromPairs` a named constructor to instantiate the container with a list of key-value pairs;
@@ -199,7 +221,7 @@ the following getter methods:
199221
- `get` returns the element associated to a specific `key`;
200222
- `pair` returns the key-pair association present at a specific `index` (negative indexes are supported);
201223

202-
the following setter methods:
224+
setter methods:
203225

204226
- `set` add an element at the end of the container if the key is new otherwise only the value is updated;
205227
- `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:
208230
- `mergeAssociative` merge multiple instances of iterable structure as associative constructs;
209231
- `mergePairs` merge multiple instances of iterable structure as pairs constructs;
210232

211-
**All setter methods are chainable.**
212-
213233
```php
214234
use Bakame\Http\StructuredFields;
215235

@@ -230,11 +250,6 @@ echo $dictionary
230250
->toHttpValue(); //returns "a=?0, z=42.0"
231251
```
232252

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-
238253
The `Parameters` instance exposes the following additional methods:
239254

240255
- `Parameters::values()` to list all existing Bare Items value as an array list;
@@ -259,10 +274,17 @@ $parameters->toHttpValue(); // returns ;b="false";foo="foo"
259274
$parameters->value('unknown'); // returns null
260275
```
261276

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;
263286

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:
266288

267289
getter methods:
268290

@@ -271,20 +293,14 @@ getter methods:
271293
- `get` to access an element at a given index (negative indexes are supported)
272294
- `has` tell whether an element is attached to the container using its `index`;
273295

274-
setter methods (**All setter methods are chainable.**)
296+
setter methods
275297

276298
- `push` to add elements at the end of the list;
277299
- `unshift` to add elements at the beginning of the list;
278300
- `insert` to add elements at a given position in the list;
279301
- `replace` to replace an element at a given position in the list;
280302
- `remove` to remove elements based on their position;
281303

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-
288304
```php
289305
use Bakame\Http\StructuredFields;
290306

@@ -302,18 +318,13 @@ $orderedList = StructuredFields\OrderedList::from(
302318
echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
303319
```
304320

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.
311322

312323
```php
313324
use Bakame\Http\StructuredFields;
314325

315326
$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
317328
$innerList->parameters->value('a'); // returns true
318329
```
319330

@@ -352,7 +363,7 @@ Credits
352363
Attribution
353364
-------
354365

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/).
356367

357368
License
358369
-------
@@ -362,3 +373,4 @@ The MIT License (MIT). Please see [License File](LICENSE) for more information.
362373
[1]: https://www.rfc-editor.org/rfc/rfc8941.html
363374
[2]: https://www.ietf.org/id/draft-ietf-httpbis-retrofit-00.html
364375
[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

Comments
 (0)