I’m proud to announce the release of a new package called bakame/http-structured-fields. This package can be used to parse and serialize HTTP headers in a more predicable way following RFC8941. If that sound a bit gibberish to you let me try to explain the problem and how this package will be a huge building block toward a broader solution.

The current mess with HTTP Headers

Anyone who has worked a bit with HTTP headers knows that to be able to read and write cookies, accept-language, cache or correlation-id headers to name but a few correctly there is a requirement to learn about each type of headers and create dedicated packages or classes for each one of them. The reason being that each are defined independently and rules that guides parsing and serializing each are unique and may sometimes lead to contradiction with another header definition. In summary the state of HTTP headers lean to that of a lawless country. The often used one survived regardless of their uniqueness in term of their definitions and broader understanding.

The new HTTP structured fields specification

While developing specification for HTTP/2 and other subsequent core RFCs a new RFC was drafted and assigned the index RFC8941 to tackle the state of HTTP fields.

Note that I am talking about fields here and no longer about headers because the HTTP protocol allows the presence of HTTP headers but also of the not so well known but equally important the HTTP trailers. HTTP headers and trailers are grouped under the term field hence the name of the RFC.

That being said, the goal of that RFC is not to provide one definition for all fields but to expose well defined and thus predicable types and structures that could make up a field so that implementors as well as consumers could easily parsed and serialized fields in an interoperability way.

Because fields are already widely used the RFC aims at fixing the issues on futur and new fields. As such most of the new headers are being defined using this new specification which means that instead of everyone coming up with their own dialect all new headers uses the same language even thought they are not telling the same story.

For instance instead of saying the header Test-Header uses a fully fledge specification, you will have to say Test-Header uses a SF-List which means that you will know how to parse the header. You will still need to validate the header against its specification but the building blocks are known and understood across the wire.

Bakame HTTP Structured fields

That’s where the new package comes handy. By strictly implementing the RFC in a framework independent way it provides the perfect middleware for any PHP application to read/write new HTTP headers in a pragmatic and efficient way. Whichever framework you are currently using you can use the package to translation your header or to translate new headers string into PHP value object that you can easily validate or use in your application business logic.

Once you have installed the package via composer you can already start using it to parse for instance the following putative HTTP header like this:

As you can see the library is able to correctly parse the header and to expose each part in a predicable way. And conversely it can recreate the header value from scratch.

When to use this library ?

As explain this library will be useful in PHP if you need to parse newly created headers. For instance it can comes handy if you want to parse Chrome newly added security headers. Chrome Accept-CH is a SF-List which means you can easily parse its content using the library:

It also can be handy if you want to retrofit current headers into the current RFC as explained in this document. (Full disclosure this is one of the main reason I built this package as they were no equivalent in PHP prior).

Which means that using the current library in the background I can write the following code

where the toRfc8941 method will look something like this

As you may have notice the retrofit algorithm tries to stay backward compatible but even for the cookie header it is not possible. For instance the expires parameters is converted to a SF Item string to avoid parsing issue. The comma (,) as a specific meaning and need to be enclosed in a string structure to avoid parsing errors.

That being said I strongly believe that the new package will help the PHP community as the whole to better embrace HTTP/2 and beyond as well as new RFC headers and trailers im the upcoming years.

Last but not least

This package would not have been possible without the prior work done by gapple and his implementation for PHP. The current package bakame\http-structured-fields is an open source project with a MIT License so contributions are more than welcome and will be fully credited. These contributions can be anything from becoming a sponsor, reporting an issue, requesting or adding missing features or simply improving or correcting some typo on the documentation website.