bakame / http-structured-fields
Structured Field Values for HTTP manipulation in PHP
Fund package maintenance!
nyamsprod
Requires
- php: ^8.1
- ext-json: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^v3.15.1
- httpwg/structured-field-tests: *@dev
- phpbench/phpbench: ^1.2.10
- phpstan/phpstan: ^1.10.14
- phpstan/phpstan-deprecation-rules: ^1.1.3
- phpstan/phpstan-phpunit: ^1.3.11
- phpstan/phpstan-strict-rules: ^1.5.1
- phpunit/phpunit: ^10.1.2
- symfony/var-dumper: ^6.2.10
README
bakame/http-structured-fields
is a framework-agnostic PHP library that allows you to parse, serialize
build and update HTTP Structured Fields in PHP according to the RFC8941.
Once installed you will be able to do the following:
use Bakame\Http\StructuredFields\{InnerList, Item, OuterList, Token}; //1 - parsing an Accept Header $headerValue = 'text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8'; $field = OuterList::fromHttpValue($headerValue); $field[2]->value()->toString(); // returns 'application/xml' $field[2]->parameter('q'); // returns (float) 0.9 $field[0]->value()->toString(); // returns 'text/html' $field[0]->parameter('q'); // returns null //2 - building a Retrofit Cookie Header echo OuterList::new( InnerList::fromAssociative(['foo', 'bar'], [ 'expire' => $expire, 'path' => '/', 'max-age' => 2500, 'secure' => true, 'httponly' => true, 'samesite' => Token::fromString('lax'), ]) ) ->toHttpValue(); // returns ("foo" "bar");expire=@1681504328;path="/";max-age=2500;secure;httponly=?0;samesite=lax
System Requirements
PHP >= 8.1 is required but the latest stable version of PHP is recommended.
Installation
Use composer:
composer require bakame/http-structured-fields
Documentation
Foreword
⚠️WARNING: While this package parses and serializes the header value, it does not validate its content. It is still required to validate the parsed data against the constraints of the corresponding header. Content validation is out of scope for this library.
Parsing and Serializing Structured Fields
Basic usage
Parsing the header value is done via the fromHttpValue
named constructor.
The method is attached to each library's structured fields representation
as shown below:
declare(strict_types=1); require 'vendor/autoload.php'; use Bakame\Http\StructuredFields\Item; // the raw HTTP field value is given by your application // via any given framework, package or super global. $headerLine = 'bar;baz=42'; //the raw header line is a structured field item $field = Item::fromHttpValue($headerLine); $field->value(); // returns Token::fromString('bar); the found token value $field->parameter('baz'); // returns 42; the value of the parameter or null if the parameter is not defined.
The fromHttpValue
method returns an instance which implements the StructuredField
interface.
The interface provides the toHttpValue
method that serializes it into a normalized RFC
compliant HTTP field string value. To ease integration, the __toString
method is
implemented as an alias to the toHttpValue
method.
use Bakame\Http\StructuredFields\Item; $field = Item::fromHttpValue('bar; baz=42; secure=?1'); echo $field->toHttpValue(); // return 'bar;baz=42;secure' // on serialization the field has been normalized // the HTTP response is build by your application // via any given framework, package or PHP native function. header('foo: '. $field->toHttpValue()); //or header('foo: '. $field);
All five (5) structured data type as defined in the RFC are provided inside the
Bakame\Http\StructuredFields
namespace. They all implement the
StructuredField
interface and expose a fromHttpValue
named constructor:
Item
Parameters
Dictionary
OuterList
(namedList
in the RFC but renamed in the package becauselist
is a reserved word in PHP.)InnerList
Advance usage
Starting with version 1.1
the internal parser has been made public in order to allow:
- clearer decoupling betwen parsing and objet building
- different parsers implementations
- improve the package usage in testing.
Each fromHttpValue
method signature has been updated to take a second optional argument
that represents the parser interface to use in order to allow parsing of the HTTP string
representation value.
By default, if no parser is provided, the package will default to use the package Parser
class,
Item::fromHttpValue(Stringable|string $httpValue, ItemParser $parser = new Parser()): Item; InnerList::fromHttpValue(Stringable|string $httpValue, InnerListParser $parser = new Parser()): InnerList; Dictionary::fromHttpValue(Stringable|string $httpValue, DictionaryParser $parser = new Parser()): Dictionary; OuterList::fromHttpValue(Stringable|string $httpValue, ListParser $parser = new Parser()): OuterList; Parameters::fromHttpValue(Stringable|string $httpValue, ParametersParser $parser = new Parser()): Parameters;
The Parser
class exposes the following method each belonging to a different contract or interface.
Parser::parseValue(Stringable|string $httpValue): ByteSequence|Token|DateTimeImmutable|string|int|float|bool; Parser::parseItem(Stringable|string $httpValue): array; Parser::parseParameters(Stringable|string $httpValue): array; Parser::parseInnerList(Stringable|string $httpValue): array; Parser::parseList(Stringable|string $httpValue): array; Parser::parseDictionary(Stringable|string $httpValue): array;
Once instantiated, calling one of the above listed method is straightforward:
use Bakame\Http\StructuredFields\Parser; $parser = new Parser(); $parser->parseValue('text/csv'); //returns Token::fromString('text/csv') $parser->parseItem('@1234567890;file=24'); //returns an array // [ // new DateTimeImmutable('@1234567890'), // ['file' => 24], // ]
While the provided default Parser
class implements all these methods you are free to only implement
the methods you need.
Accessing Structured Fields Values
RFC Value type
Per the RFC, items can have different types that are translated to PHP using:
- native type where possible
- specific classes defined in the package namespace to represent non-native type
The table below summarizes the item value type.
RFC Type | PHP Type | Package Enum Type |
---|---|---|
Integer | int |
Type::Integer |
Decimal | float |
Type::Decimal |
String | string |
Type::String |
Boolean | bool |
Type::Boolean |
Token | class Token |
Type::Token |
Byte Sequence | class ByteSequence |
Type::ByteSequence |
Date | class DateTimeImmutable |
Type::Date |
The Enum Type
which list all available types can be use to determine the RFC type
corresponding to a PHP structure using the Type::fromValue
static method.
The method will throw if the structure is not recognized Alternatively it is possible
to use the Type::tryFromValue
which will instead return null
on unindentified type.
On success both methods returns the corresponding enum Type
.
use Bakame\Http\StructuredFields\Type; echo Type::fromValue(42); // returns Type::Integer echo Type::fromValue(42.0)->name; // returns 'Decimal' echo Type::fromValue(new SplTempFileObject()); // throws InvalidArgument echo Type::tryFromValue(new SplTempFileObject()); // returns null
To ease validation a Type::equals
method is exposed to check if the Item
has
the expected type. It can also be used to compare types.
use Bakame\Http\StructuredFields\Type; $field = Item::fromHttpValue('"foo"'); Type::Date->equals($field); // returns false Type::String->equals($field); // returns true; Type::Boolean->equals(Type::String); // returns false
The RFC defines two (2) specific data types that can not be represented by
PHP default type system, for them, we have defined two classes Token
and ByteSequence
to help with their representation.
use Bakame\Http\StructuredFields\Token; use Bakame\Http\StructuredFields\ByteSequence; Token::fromString(string|Stringable $value): Token ByteSequence::fromDecoded(string|Stringable $value): ByteSequence; ByteSequence::fromEncoded(string|Stringable $value): ByteSequence;
Both classes are final and immutable; their value can not be modified once instantiated. To access their value, they expose the following API:
use Bakame\Http\StructuredFields\Token; use Bakame\Http\StructuredFields\ByteSequence; $token = Token::fromString('application/text+xml'); echo $token->toString(); // returns 'application/text+xml' $byte = ByteSequence::fromDecoded('Hello world!'); $byte->decoded(); // returns 'Hello world!' $byte->encoded(); // returns 'SGVsbG8gd29ybGQh' $token->equals($byte); // will return false; $byte->equals(ByteSequence::fromEncoded('SGVsbG8gd29ybGQh')); // will return true $token->type(); // returns Type::Token enum $byte->type(); // returns Type::ByteSequence
⚠️WARNING: Both classes DO NOT expose the Stringable
interface to distinguish them
from a string or a string like object
Item
The defined types are all attached to an Item
object where their value and
type are accessible using the following methods:
use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Type; $item = Item::fromHttpValue('@1234567890'); $item->type(); // return Type::Date; $item->value() // return the equivalent to DateTimeImmutable('@1234567890');
Containers
All containers objects implement PHP IteratorAggregate
, Countable
and ArrayAccess
interfaces. Their members can be accessed using the following shared methods
$container->keys(): array<string|int>; $container->has(string|int ...$offsets): bool; $container->get(string|int $offset): StrucuredField; $container->hasMembers(): bool; $container->hasNoMembers(): bool;
The get
method will throw an InvalidOffset
exception if no member exists for the given $offset
.
To avoid invalid states, ArrayAccess
modifying methods throw a ForbiddenOperation
if you try to use them on any container object:
use Bakame\Http\StructuredFields\Parameters; $value = Parameters::fromHttpValue(';a=foobar']); $value->has('b'); // return false $value['a']->value(); // return 'foobar' $value['b']; // triggers a InvalidOffset exception, the index does not exist $value['a'] = 23 // triggers a ForbiddenOperation exception unset($value['a']); // triggers a ForbiddenOperation exception
The Dictionary
and Parameters
classes also allow accessing its members as pairs:
$container->hasPair(int ...$offsets): bool; $container->pair(int $offset): array{0:string, 1:StructuredField}; $container->toPairs(): iterable<array{0:string, 1:StructuredField}>;
The pair
method will throw an InvalidOffset
exception if no member exists for the given $offset
.
Accessing the parameters values
Accessing the associated Parameters
instance attached to an InnerList
or a Item
instances
is done using the following methods:
use Bakame\Http\StructuredFields\InnerList; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Parameters; $field->parameter(string $key): ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool|null; $field->parameters(): Parameters; $field->parameterByIndex(int $index): array{0:string, 1:ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|boo}|array{} InnerList::toPair(): array{0:list<Item>, 1:Parameters}>}; Item::toPair(): array{0:ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool, 1:Parameters}>};
- The
parameter
method will returnnull
if no value is found for the given key. - The
parameterByIndex
method is added inversion 1.1.0
and returns an empty array if no parameter is found for the given index.
Building and Updating Structured Fields Values
Every value object can be used as a builder to create an HTTP field value. Because we are using immutable value objects any change to the value object will return a new instance with the changes applied and leave the original instance unchanged.
Items value
The Item
value object exposes the following named constructors to instantiate
bare items (ie: item without parameters attached to them).
use Bakame\Http\StructuredFields\ByteSequence; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Token; Item:new(DateTimeInterface|ByteSequence|Token|string|int|float|bool $value): self Item::fromDecodedByteSequence(Stringable|string $value): self; Item::fromEncodedByteSequence(Stringable|string $value): self; Item::fromToken(Stringable|string $value): self; Item::fromString(Stringable|string $value): self; Item::fromDate(DateTimeInterface $datetime): self; Item::fromDateFormat(string $format, string $datetime): self; Item::fromDateString(string $datetime, DateTimeZone|string|null $timezone = null): self; Item::fromTimestamp(int $value): self; Item::fromDecimal(int|float $value): self; Item::fromInteger(int|float $value): self; Item::true(): self; Item::false(): self;
To update the Item
instance value, use the withValue
method:
use Bakame\Http\StructuredFields\Item; Item::withValue(DateTimeInterface|ByteSequence|Token|string|int|float|bool $value): static
Ordered Maps
The Dictionary
and Parameters
are ordered map instances. They can be built using their keys with an associative iterable structure as shown below
use Bakame\Http\StructuredFields\Dictionary; $value = Dictionary::fromAssociative([ 'b' => Item::false(), 'a' => Item::fromToken('bar'), 'c' => new DateTimeImmutable('2022-12-23 13:00:23'), ]); echo $value->toHttpValue(); //"b=?0, a=bar, c=@1671800423" echo $value; //"b=?0, a=bar, c=@1671800423"
or using their indexes with an iterable structure of pairs (tuple) as defined in the RFC:
use Bakame\Http\StructuredFields\Parameters; use Bakame\Http\StructuredFields\Item; $value = Parameters::fromPairs(new ArrayIterator([ ['b', Item::false()], ['a', Item::fromToken('bar')], ['c', new DateTime('2022-12-23 13:00:23')] ])); echo $value->toHttpValue(); //;b=?0;a=bar;c=@1671800423 echo $value; //;b=?0;a=bar;c=@1671800423
If the preference is to use the builder pattern, the same result can be achieved with the following steps:
- First create a
Parameters
or aDictionary
instance using thenew
named constructor which returns a new instance with no members. - And then, use any of the following modifying methods to populate it.
$map->add(string $key, $value): static; $map->append(string $key, $value): static; $map->prepend(string $key, $value): static; $map->mergeAssociative(...$others): static; $map->mergePairs(...$others): static; $map->remove(string|int ...$key): static;
As shown below: `
use Bakame\Http\StructuredFields\Dictionary; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Token; $value = Dictionary::new() ->add('a', InnerList::new( Item::fromToken('bar'), Item::fromString('42'), Item::fromInteger(42), Item::fromDecimal(42) )) ->prepend('b', Item::false()) ->append('c', Item::fromDateString('2022-12-23 13:00:23')) ; echo $value->toHttpValue(); //b=?0, a=(bar "42" 42 42.0), c=@1671800423 echo $value; //b=?0, a=(bar "42" 42 42.0), c=@1671800423
Since version 1.1.0
it is possible to also build Dictionary
and Parameters
instances
using indexes and pair as per described in the RFC.
The $pair
parameter is a tuple (ie: an array as list with exactly two members) where:
- the first array member is the parameter
$key
- the second array member is the parameter
$value
// since version 1.1 $map->unshift(array ...$pairs): static; $map->push(array ...$pairs): static; $map->insert(int $key, array ...$pairs): static; $map->replace(int $key, array $pair): static; $map->removeByKeys(string ...$keys): static; $map->removeByIndices(int ...$indices): static;
We can rewrite the previous example
use Bakame\Http\StructuredFields\Dictionary; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Token; $value = Dictionary::new() ->push( ['a', InnerList::new( Item::fromToken('bar'), Item::fromString('42'), Item::fromInteger(42), Item::fromDecimal(42) )], ['c', Item::true()] ) ->unshift(['b', Item::false()]) ->replace(2, ['c', Item::fromDateString('2022-12-23 13:00:23')]) ; echo $value->toHttpValue(); //b=?0, a=(bar "42" 42 42.0), c=@1671800423 echo $value; //b=?0, a=(bar "42" 42 42.0), c=@1671800423
⚠️WARNING: on duplicate keys
pair values are merged as per RFC logic.
The remove
always accepted string or integer as input. Since version 1.1
the method is fixed to
remove the corresponding pair if its index is given to the method.
<?php use Bakame\Http\StructuredFields\Dictionary; $field = Dictionary::fromHttpValue('b=?0, a=(bar "42" 42 42.0), c=@1671800423'); - echo $field->remove('b', 2)->toHttpValue(); // returns a=(bar "42" 42 42.0), c=@1671800423 + echo $field->remove('b', 2)->toHttpValue(); // returns a=(bar "42" 42 42.0)
If a stricter approach is needed, use the following new methods removeByIndices
and/or removeByKeys
:
use Bakame\Http\StructuredFields\Parameters; $field = Parameters::fromHttpValue(';expire=@1681504328;path="/";max-age=2500;secure;httponly=?0;samesite=lax'); echo $field->removeByIndices(4, 2, 0)->toHttpValue(); // returns ;path="/";secure;samesite=lax echo $field->removeByKeys('expire', 'httponly', 'max-age')->toHttpValue(); // returns ;path="/";secure;samesite=lax
Automatic conversion
For all containers, to ease instantiation the following automatic conversion are applied on the member argument of each modifying methods.
If the submitted type is:
- a
StructuredField
implementing object, it will be passed as is - an iterable structure, it will be converted to an
InnerList
instance usingInnerList::new
- otherwise, it is converted into an
Item
using theItem::new
named constructor.
If no conversion is possible an InvalidArgument
exception will be thrown.
This means that both constructs below built equal objects
use Bakame\Http\StructuredFields\Dictionary; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Token; echo Dictionary::new() ->add('a', InnerList::new( Item::fromToken('bar'), Item::fromString('42'), Item::fromInteger(42), Item::fromDecimal(42) )) ->prepend('b', Item::false()) ->append('c', Item::fromDateString('2022-12-23 13:00:23')) ->toHttpValue() ; echo Dictionary::new() ->add('a', [Token::fromString('bar'), '42', 42, 42.0]) ->prepend('b', false) ->append('c', new DateTimeImmutable('2022-12-23 13:00:23')) ->toHttpValue() ; // both will return 'b=?0, a=(bar "42" 42 42.0), c=@1671800423
Of course, it is possible to mix both notations.
Lists
To create OuterList
and InnerList
instances you can use the new
named constructor
which takes a single variadic parameter $members
:
use Bakame\Http\StructuredFields\InnerList; use Bakame\Http\StructuredFields\ByteSequence; $list = InnerList::new( ByteSequence::fromDecoded('Hello World'), 42.0, 42 ); echo $list->toHttpValue(); //'(:SGVsbG8gV29ybGQ=: 42.0 42)' echo $list; //'(:SGVsbG8gV29ybGQ=: 42.0 42)'
Once again, the builder pattern can be used via a combination of the new
named constructor and the use any of the following modifying methods.
$list->unshift(...$members): static; $list->push(...$members): static; $list->insert(int $key, ...$members): static; $list->replace(int $key, $member): static; $list->remove(int ...$key): static;
as shown below
use Bakame\Http\StructuredFields\ByteSequence; use Bakame\Http\StructuredFields\InnerList; $list = InnerList::new() ->unshift('42') ->push(42) ->insert(1, 42.0) ->replace(0, ByteSequence::fromDecoded('Hello World')); echo $list->toHttpValue(); //'(:SGVsbG8gV29ybGQ=: 42.0 42)' echo $list; //'(:SGVsbG8gV29ybGQ=: 42.0 42)'
Adding and updating parameters
To ease working with instances that have a Parameters
object attached to, the following
methods are added:
use Bakame\Http\StructuredFields\ByteSequence; use Bakame\Http\StructuredFields\InnerList; use Bakame\Http\StructuredFields\Item; use Bakame\Http\StructuredFields\Token; //@type SfItemInput ByteSequence|Token|DateTimeInterface|string|int|float|bool Item::fromAssociative(SfItemInput $value, Parameters|iterable<string, SfItemInput> $parameters): self; Item::fromPair(array{0:SfItemInput, 1:Parameters|iterable<array{0:string, 1:SfItemInput}>} $pair): self; InnerList::fromAssociative(iterable<SfItemInput> $value, Parameters|iterable<string, SfItemInput> $parameters): self; InnerList::fromPair(array{0:iterable<SfItemInput>, Parameters|iterable<array{0:string, 1:SfItemInput}>} $pair): self;
The following example illustrate how to use those methods:
use Bakame\Http\StructuredFields\Dictionary; use Bakame\Http\StructuredFields\Item; echo Item::fromAssociative( Token::fromString('bar'), ['baz' => 42] )->toHttpValue(), PHP_EOL; echo Item::fromPair([ Token::fromString('bar'), [['baz', 42]], ])->toHttpValue(), PHP_EOL; //both methods return `bar;baz=42`
Both objects provide additional modifying methods to help deal with parameters.
You can attach and update the associated Parameters
instance using the following methods.
$field->addParameter(string $key, mixed $value): static; $field->appendParameter(string $key, mixed $value): static; $field->prependParameter(string $key, mixed $value): static; $field->withoutParameters(string ...$keys): static; // this method is deprecated as of version 1.1 use withoutParametersByKeys instead $field->withoutAnyParameter(): static; $field->withParameters(Parameters $parameters): static;
Since version 1.1
it is also possible to use the index of each member to perform additional
modifications.
$field->pushParameters(array ...$pairs): static $field->unshiftParameters(array ...$pairs): static $field->insertParameters(int $index, array ...$pairs): static $field->replaceParameter(int $index, array $pair): static $field->withoutParametersByKeys(string ...$keys): static $field->withoutParametersByIndices(int ...$indices): static
The $pair
parameter is a tuple (ie: an array as list with exactly two members) where:
- the first array member is the parameter
$key
- the second array member is the parameter
$value
⚠️WARNING: The return value will be the parent class an NOT a Parameters
instance
use Bakame\Http\StructuredFields\InnerList; use Bakame\Http\StructuredFields\Item; echo InnerList::new('foo', 'bar') ->addParameter('expire', Item::fromDateString('+30 minutes')) ->addParameter('path', '/') ->addParameter('max-age', 2500) ->toHttpValue(); echo InnerList::new('foo', 'bar') ->pushParameter( ['expire', Item::fromDateString('+30 minutes')], ['path', '/'], ['max-age', 2500], ) ->toHttpValue(); // both flow return the InnerList HTTP value // ("foo" "bar");expire=@1681538756;path="/";max-age=2500
Contributing
Contributions are welcome and will be fully credited. Please see CONTRIBUTING and CODE OF CONDUCT for details.
Testing
The library:
- has a PHPUnit test suite
- has a coding style compliance test suite using PHP CS Fixer.
- has a code analysis compliance test suite using PHPStan.
- is compliant with the language agnostic HTTP Structured Fields Test suite.
To run the tests, run the following command from the project folder.
composer test
Security
If you discover any security related issues, please email nyamsprod@gmail.com instead of using the issue tracker.
Credits
Attribution
The package internal parser is heavily inspired by previous work done by Gapple on Structured Field Values for PHP.
License
The MIT License (MIT). Please see License File for more information.