Improve Public API

Author: nyamsprod

CHANGELOG.md

@@ -6,10 +6,16 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
-- None
+- `ParameterAccess` interface updated with 3 new methods to ease parameter members modification.
+- Support for `Stringable` instance to `Item::from`, the instances will be converted to the string data type.
+- `Parameter::new` named constructor to create a new instance without any parameter.
+- `Dictionnary::new` named constructor to create a new instance without any parameter.
+- `InnerList::new` named constructor to create a new instance with members as variadic arguments.
+- `OrderedList::new` named constructor to create a new instance with members as variadic arguments.
 
 ### Fixed
 
+- **[BC Break]** `::fromAssociative`, `::fromList`, `::fromPairs` methods require iterable arguments without default value.
 - **[BC Break]** `Item::value` method returns the Item (returns value can be `float|int|string|bool|ByteSequence|Token`).
 - `InnerList::parameters` is no longer accessible as a public readonly property.
 
@@ -19,7 +25,8 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Removed
 
-- None
+- **[BC Break]** `InnerList::from` named constructor use `InnerList::new` method instead.
+- **[BC Break]** `OrderedList::from` named constructor use `OrderedList::new` method instead.
 
 ## [0.6.0] - 2022-11-12
 
@@ -176,7 +183,8 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 **Initial release!**
 
-[Next]: https://github.com/bakame-php/http-structured-fields/compare/0.5.0...master
+[Next]: https://github.com/bakame-php/http-structured-fields/compare/0.6.0...master
+[0.6.0]: https://github.com/bakame-php/http-structured-fields/compare/0.5.0...0.6.0
 [0.5.0]: https://github.com/bakame-php/http-structured-fields/compare/0.4.0...0.5.0
 [0.4.0]: https://github.com/bakame-php/http-structured-fields/compare/0.3.0...0.4.0
 [0.3.0]: https://github.com/bakame-php/http-structured-fields/compare/0.2.0...0.3.0

Makefile

@@ -1,5 +1,4 @@
-Structured Field Values for PHP
-=======================================
+# HTTP Structured Fields for PHP
 
 [![Author](http://img.shields.io/badge/author-@nyamsprod-blue.svg?style=flat-square)](https://twitter.com/nyamsprod)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
@@ -20,21 +19,19 @@ The package can be used to:
 - build or update HTTP Structured Fields in a predicable way;
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Item;
 
-$field = StructuredFields\Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
+$field = Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
 echo $field->toHttpValue();              // display "/terms";rel="copyright";anchor="#foo"
 echo $field->value();                    // display "/terms"
 echo $field->parameters()['rel']->value(); // display "copyright"
 ```
 
-System Requirements
--------
+## System Requirements
 
 **PHP >= 8.1** is required but the latest stable version of PHP is recommended.
 
-Installation
-------------
+## Installation
 
 Use composer:
 
@@ -50,24 +47,21 @@ or download the library and:
 ~~~php
 require 'path/to/http-structured-fields/repo/autoload.php';
 
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\OrderedList;
 
-$list = StructuredFields\OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
+$list = OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
 echo $list[-1]->value(); // returns '/member/*/comments'
 ~~~
 
-Documentation
-------------
+## Documentation
 
 Full documentation can be found in the [docs](/docs).
 
-Contributing
--------
+## 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.
 
-Testing
--------
+## Testing
 
 The library:
 
@@ -79,27 +73,23 @@ The library:
 To run the tests, run the following command from the project folder.
 
 ``` bash
-$ composer test
+composer test
 ```
 
-Security
--------
+## Security
 
 If you discover any security related issues, please email nyamsprod@gmail.com instead of using the issue tracker.
 
-Credits
--------
+## Credits
 
 - [ignace nyamagana butera](https://github.com/nyamsprod)
 - [All Contributors](https://github.com/bakame-php/http-structured-fields/contributors)
 
-Attribution
--------
+## Attribution
 
 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/).
 
-License
--------
+## License
 
 The MIT License (MIT). Please see [License File](LICENSE) for more information.
 

README.md

@@ -30,8 +30,8 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^v3.13.2",
         "httpwg/structured-field-tests": "*@dev",
-        "phpstan/phpstan": "^1.9.8",
-        "phpstan/phpstan-strict-rules": "^1.4.4",
+        "phpstan/phpstan": "^1.9.9",
+        "phpstan/phpstan-strict-rules": "^1.4.5",
         "phpstan/phpstan-phpunit": "^1.3.3",
         "phpstan/phpstan-deprecation-rules": "^1.1.1",
         "phpunit/phpunit": "^9.5.27"

composer.json

@@ -14,15 +14,17 @@ representation of the field and to serialize the value object back to the textua
 - Serializing is done via a common `toHttpValue` public method. The method returns the **normalized string** representation suited for HTTP textual representation.
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Dictionary;
+use Bakame\Http\StructuredFields\Item;
+use Bakame\Http\StructuredFields\OrderedList;
 
-$dictionary = StructuredFields\Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
+$dictionary = Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
 echo $dictionary->toHttpValue(); // 'a=?0, b, c;foo=bar'
 
-$list = StructuredFields\OrderedList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
+$list = OrderedList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
 echo $list->toHttpValue(); // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
 
-$item = StructuredFields\Item::fromHttpValue('"foo";a=1;b=2');
+$item = Item::fromHttpValue('"foo";a=1;b=2');
 echo $item->toHttpValue(); // "foo";a=1;b=2
 ```
 

docs/basic-usage.md

@@ -1,9 +1,9 @@
 # Containers
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Parameters;
 
-$parameters = StructuredFields\Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
+$parameters = Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
 count($parameters); // returns 3
 $parameters->hasMembers(); // returns true
 $parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'

docs/containers.md

@@ -1,5 +1,5 @@
-Structured Field Values for PHP
-=======================================
+HTTP Structured Fields For PHP
+=====================
 
 [![Author](http://img.shields.io/badge/author-@nyamsprod-blue.svg?style=flat-square)](https://twitter.com/nyamsprod)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
@@ -20,9 +20,9 @@ The package can be used to:
 - build or update HTTP Structured Fields in a predicable way;
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Item;
 
-$field = StructuredFields\Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
+$field = Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
 echo $field->toHttpValue();              // display "/terms";rel="copyright";anchor="#foo"
 echo $field->value();                    // display "/terms"
 echo $field->parameters['rel']->value(); // display "copyright"
@@ -50,9 +50,9 @@ or download the library and:
 ~~~php
 require 'path/to/http-structured-fields/repo/autoload.php';
 
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\OrderedList;
 
-$list = StructuredFields\OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
+$list = OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
 echo $list[-1]->value(); // returns '/member/*/comments'
 ~~~
 

docs/index.md

@@ -22,9 +22,9 @@ The table below summarizes the item value type.
 ### Token
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Token;
 
-$token = StructuredFields\Token::fromString('bar');
+$token = Token::fromString('bar');
 
 echo $token->value; // displays 'bar'
 ```
@@ -38,10 +38,10 @@ The class also exposes its value via the public readonly property `value` to ena
 ### Byte Sequence
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\ByteSequence;
 
-$sequenceFromDecoded = StructuredFields\ByteSequence::fromDecoded("Hello World");
-$sequenceFromEncoded = StructuredFields\ByteSequence::fromEncoded("SGVsbG8gV29ybGQ=");
+$sequenceFromDecoded = ByteSequence::fromDecoded("Hello World");
+$sequenceFromEncoded = ByteSequence::fromEncoded("SGVsbG8gV29ybGQ=");
 
 echo $sequenceFromEncoded->decoded(); // displays 'Hello World'
 echo $sequenceFromDecoded->encoded(); // displays 'SGVsbG8gV29ybGQ='
@@ -63,9 +63,9 @@ keys are strings and the value are bare items. Their public API is covered in th
 **Exception will be thrown when trying to access or serialize a parameter object containing non-bare items.**
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Item;
 
-$item = StructuredFields\Item::from("hello world", ["a" => true]);
+$item = Item::from("hello world", ["a" => true]);
 $item->value();    // returns "hello world"
 $item->isString(); // returns true
 $item->isToken();  // returns false
@@ -88,11 +88,12 @@ Those listed named constructors expect a string or a stringable object as its fi
 same argument definition as in `Item::from` for parameters argument.
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Item;
 
-$item = StructuredFields\Item::fromPair([
+$item = Item::fromPair([
     "hello world", [
-        ["a", StructuredFields\ByteSequence::fromDecoded("Hello World")],
+        ["a", ByteSequence::fromDecoded("Hello World")],
     ]
 ]);
 $item->value();    // returns "hello world"
@@ -115,23 +116,24 @@ Once instantiated, accessing `Item` properties is done via:
 - the method `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\ByteSequence;
+use Bakame\Http\StructuredFields\Item;
 
-$item = StructuredFields\Item::from(StructuredFields\ByteSequence::fromEncoded("SGVsbG8gV29ybGQ="));
+$item = Item::from(ByteSequence::fromEncoded("SGVsbG8gV29ybGQ="));
 $item->isByteSequence(); // returns true
 echo $item->value();     // returns StructuredFields\ByteSequence::fromEncoded("SGVsbG8gV29ybGQ=");
 ```
 
 **Of note: to instantiate a decimal number type a float MUST be used as the first argument of `Item::from`.**
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\Item;
 
-$decimal = StructuredFields\Item::from(42.0);
+$decimal = Item::from(42.0);
 $decimal->isDecimal(); //return true
 $decimal->isInteger(); //return false
 
-$item = StructuredFields\Item::fromPair([42]);
+$item = Item::fromPair([42]);
 $item->isDecimal(); //return false
 $item->isInteger(); //return true
 ```

docs/item.md

@@ -17,7 +17,7 @@ Both classes expose the following:
 named constructors:
 
 - `fromList` instantiates the container with a list of members in an iterable construct;
-- `from` instantiates the container with a list of members as variadic;
+- `new` instantiates the container with a list of members as variadic;
 
 setter methods
 
@@ -34,17 +34,20 @@ In addition to `StructuredField` specific interfaces, both classes implements:
 - PHP `ArrayAccess` interface.
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\InnerList;
+use Bakame\Http\StructuredFields\Item;
+use Bakame\Http\StructuredFields\OrderedList;
+use Bakame\Http\StructuredFields\Token;
 
-$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
+$innerList = InnerList::fromList([42, 42.0, "42"], ["a" => true]);
 $innerList->has(2); //return true
 $innerList->has(42); //return false
-$innerList->push(StructuredFields\Token::fromString('forty-two'));
+$innerList->push(Token::fromString('forty-two'));
 $innerList->remove(0, 2);
 echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
 
-$orderedList = StructuredFields\OrderedList::from(
-    StructuredFields\Item::from("42", ["foo" => "bar"]), 
+$orderedList = OrderedList::new(
+    Item::from("42", ["foo" => "bar"]), 
     $innerList
 );
 echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
@@ -53,12 +56,13 @@ echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
 Same example using the `ArrayAccess` interface.
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\InnerList;
+use Bakame\Http\StructuredFields\Token;
 
-$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
+$innerList = InnerList::fromList([42, 42.0, "42"], ["a" => true]);
 isset($innerList[2]); //return true
 isset($innerList[42]); //return false
-$innerList[] = StructuredFields\Token::fromString('forty-two');
+$innerList[] = Token::fromString('forty-two');
 unset($innerList[0], $innerList[2]);
 echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
 ```
@@ -69,9 +73,10 @@ keys. Be aware that re-indexation behaviour may affect
 your logic**
 
 ```php
-use Bakame\Http\StructuredFields;
+use Bakame\Http\StructuredFields\OrderedList;
+use Bakame\Http\StructuredFields\Token;
 
-$innerList = StructuredFields\OrderedList::fromList([42, 42.0]);
-$innerList[2] = StructuredFields\Token::fromString('forty-two'); // will throw
+$innerList = OrderedList::fromList([42, 42.0]);
+$innerList[2] = Token::fromString('forty-two'); // will throw
 echo $innerList->toHttpValue(), PHP_EOL;
 ```