Download the PHP package bakame/http-structured-fields without Composer

HTTP Structured Fields for PHP

bakame/http-structured-fields is a framework-agnostic PHP library that allows you to parse, serialize create, update and validate HTTP Structured Fields in PHP according to the RFC9651.

Once installed you will be able to do the following:

System Requirements

PHP >= 8.1 is required but the latest stable version of PHP is recommended.

Installation

Use composer:

Documentation

[!WARNING] The documentation for v2 is still not fully finished please refers to version 1.x for the most recent and stable documentation.

The package is compliant against RFC9651 as such it exposes all the data type and all the methods expected to comply with the RFC requirements

Basic Usage

Structured Fields are a set of rules established to allow for easier and more predicable HTTP header or trailer process. The package abstracts this complexity and define useful features to enable better validation.

While The RFC defines 5 (five) structured data type, you can access then using the DataType enum for a quick usage.

Because there are 2 RFCs (RFC8941 which is now obsolete and superseded by RFC9651), the package provides an Enum called Ietf to help you choose which RFC you need during serialization and parsing. If the Enum is not used the package will fallback to using the latest stable RFC. (ie: RFC9651).

To simplify your code, your can use this alternative syntax:

[!WARNING] If parsing or serializing is not possible, a SyntaxError exception is thrown with the information about why the conversion could not be achieved.

At any given moment when building your structured field you can use the Ietf::supports method to know whether your current work is valid against any of the RFC.

Accessing Structured Fields Values

The package provides methods to access the field values and convert them to PHP type whenever possible.The table below summarizes the value type.

[!WARNING] The translation to PHP native type does not mean that all PHP values are usable. for instance not all integer are valid integer for structured fields and not all string are valid string according to the RFCs.

For headers or trailer when the index is important the package allows selecting parameters by name or by 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).

To update the Item instance value, use the withValue method:

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

or using their indexes with an iterable structure of pairs (tuple) as defined in the RFC:

If the preference is to use the builder pattern, the same result can be achieved with the following steps:

• First create a Parameters or a Dictionary instance using the new named constructor which returns a new instance with no members.
• And then, use any of the following modifying methods to populate it.

As shown below: `

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

We can rewrite the previous example

[!CAUTION] on duplicate keys pair values are merged as per RFC logic.

The remove always accepted string or integer as input.

If a stricter approach is needed, use the following new methods removeByIndices and/or removeByKeys:

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 using InnerList::new
• otherwise, it is converted into an Item using the Item::new named constructor.

If no conversion is possible an InvalidArgument exception will be thrown.

This means that both constructs below built equal objects

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:

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.

as shown below

It is also possible to create an OuterList based on an iterable structure of pairs.

The pairs definitions are the same as for creating either a InnerList or an Item using their respective fromPair method.

Adding and updating parameters

To ease working with instances that have a Parameters object attached to, the following methods are added:

The following example illustrate how to use those methods:

Both objects provide additional modifying methods to help deal with parameters. You can attach and update the associated Parameters instance using the following methods.

It is also possible to use the index of each member to perform additional modifications.

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

Contributing

Contributions are welcome and will be fully credited. Please see 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.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• ignace nyamagana butera
• All Contributors

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.