gapple / structured-fields Goto Github PK

View Code? Open in Web Editor NEW

4.0 3.0 0.0 160 KB

PHP Library for Structured Field Values for HTTP

License: MIT License

PHP 100.00%

structured-headers http php structured-fields rfc8941

structured-fields's Introduction

Structured Field Values for PHP

Parser and serializer for the Structured Field Values for HTTP specification.

Installation

Using composer:

composer require gapple/structured-fields

API

The Parser class provides static methods to convert a header string to structured data.
If the string cannot be parsed, a ParseException is thrown.

Parser::parseItem(string): Item;
Parser::parseList(string): OuterList;
Parser::parseDictionary(string): Dictionary;

The Serializer class provides static methods to convert structured data to a header string.
If the input cannot be serialized, a SerializeException is thrown.

Serializer::serializeItem(mixed, ?object): string;
Serializer::serializeList(iterable): string;
Serializer::serializeDictionary(object): string;

structured-fields's People

Contributors

Stargazers

Watchers

structured-fields's Issues

Drop support for PHP 7.2

PHP 7.2 is no longer supported as of 30 Nov 2020 https://www.php.net/eol.php

Allow * for dictionary member name

* is now a valid initial character for dictionary keys

see httpwg/http-extensions#1068

The test suite runs against httpwg/structured-header-tests, so new tests may cause new failures which wouldn't be detected until new commits are pushed (and they may be unrelated to the pushed changes). Running the test suite periodically will help quickly detecting issues, and isolate errors in new tests from errors introduced in changes.

Drop support for PHP 7

The library currently supports PHP ^7.3

Packagist reports about 10% of installs are on still on PHP 7
There aren't any ^8.0 language features that would make a big impact

Alias main branch

Setting up an alias will allow composer to fetch the main branch as ^1.0.x-dev

https://getcomposer.org/doc/articles/aliases.md

PHP mangles large numbers

gapple\Tests\StructuredHeaders\RulesetNumberGeneratedTest needs to skip two rules when testing serialization due to PHP rounding / truncating values.

'15 digit, 3 fractional small decimal'
'15 digit, 3 fractional large decimal'

https://3v4l.org/hGX94

$ php -a
php > var_dump(111111111111.111);
double(111111111111.11)
php > var_dump(999999999999.999);
double(1000000000000)
php > var_dump(999999999999.995);
double(999999999999.99)

The same rules don't fail parsing because the parsed and expected values receive the same truncation.

True dictionary value with parameters

Previously boolean dictionary values always required an explicit value if they also had any parameters (b and c are both true):

a=?0, b, c=?1; foo=bar

But now can shortened the same way as without parameters:

a=?0, b, c; foo=bar

see httpwg/http-extensions#1083

Implement Serialization-only tests

Test cases were added for serialization: httpwg/structured-field-tests#35

Check for custom tests that are covered by these new rules
Contribute remaining serialization tests upstream

Add Date type handling

3.3.7. Dates
Date values can be conveyed in Structured Fields.
Dates have a data model that is similar to Integers, representing a (possibly negative) delta in seconds from January 1, 1970 00:00:00 UTC, excluding leap seconds.
For example:
Example-Date: @1659578233

Incorrect parsing of list which contain more than one string item

print_r(\gapple\StructuredFields\Parser::parseList('"one", 1, 42;towel;panic=?0, "two"'));

Array
(
    [0] => Array
        (
            [0] => one", 1, 42;towel;panic=?0, "two
            [1] => stdClass Object
                (
                )
        )
)

print_r(\gapple\StructuredFields\Parser::parseList('"\"Not\\A;Brand";v="99", "Chromium";v="86"'));

Array
(
    [0] => Array
        (
            [0] => "Not\A;Brand";v="99", "Chromium";v="86
            [1] => stdClass Object
                (
                )
        )
)

Index access to Parameters and Dictionaries

According to the spec 3.1.2, 3.2

Implementations MUST provide access to [Parameters and Dictionaries] both by index and by key. Specifications MAY use either means of accessing them.

Parameters and Dictionaries are currently both parsed to stdClass objects, and the typed objects that are introduced in #29 do not currently allow accessing by index.

Cleanup StructuredHeaders namespace

The StructuredHeaders namespace compatibility code should be removed for 1.0.0

Typed Data

Currently the parser returns arrays and stdClass objects, and the serializer expects the same.

It would probably be helpful to have Item, List, InnerList, Dictionary, Parameters classes. I don't think classes for bare items are necessary (other than the existing Bytes and Token, which are needed to differentiate from strings).

Providing array / property access should be able to retain compatibility with existing code that expects un-typed data.

Item and InnerList are tuples that contain a value and parameters fields, which should remain accessible by index (0 and 1) to be compatible with the current array format.
List is a numerically indexed array
Dictionary, and Parameters are ordered maps

Add support for Display String type

httpwg/structured-field-tests#85
https://www.ietf.org/archive/id/draft-ietf-httpbis-sfbis-04.html#name-display-strings

Improve typehinting for Item value

I ran into some quirks getting PhpStorm to understand either a phpstan global alias or a local alias on the Item class that was imported elsewhere.