Allow customization of `ParamValueConverterRegistry`

[filecage]

Abstract

The current constructor of the Psr17Client requires an instance of RequestFactory which then requires an instance of ParamValueConverterRegistry.

As far as I understand, ParamValueConverterRegistry is responsible for converting query parameters into a usable format for the HTTP API.

RequestFactory and ParamValueConverterRegistry are both implemented as final, so there is no way to apply any customization in the userland.

Use Case

For my current use case, I would like to change the way of transmitting any time-related value to my ClickHouse instance. I am using DateTimeInterface compatible objects in my code and pass them as parameters to clickhouse, but this library strips the timezone information:

$client->selectWithParams('SELECT foo FROM bar WHERE ts < {MyDatetime:Datetime}', [
    'MyDatetime' => new DateTimeImmutable('2024-12-04T14:44:05+01:00')
]);

The parameter is being sent as

2024-12-04 14:44:05
--20c9f7b0c7e9cceb8c51a1e952f2284cfb6ed4ad
Content-Disposition: form-data; name="param_MyDatetime"
Content-Length: 19

The readme clearly states that it's my obligation to correctly handle timezones and pass them to the library in a way that the clickhouse instance can process it (and/or use the timezone conversion of the library).

However, I'd prefer to have my datetime objects converted to a unix timestamp instead (or a ISO8601 string with tz/offset information and then have Clickhouse parse that with date_time_input_format=best_effort.

Possible Solutions

• Removing final from ParamValueConverterRegistry
• Allow overwriting the default value converters inside ParamValueConverterRegistry, either by passing them to the constructor or by adding a setConverter (string $type, callable $closure) method (personally preferred)

Obviously, there are more possible solutiouns, but these seem to be the least intrusive to me.

Let me know what you think, I'm happy to provide a PR.

[simPod]

Hi!

the ParamValueConverterRegistry was designed with intention to allow extension.

I'm definitely open to allow passing converter overrides via constructor and then just array_merge it with default one.

I'll look at the timezone thingie later (tomorrow?)

[filecage]

I have implemented the functionality in PR #286, please have a look and feel free to comment.

@simPod
I'll look at the timezone thingie later (tomorrow?)

I don't think there's much to look at. As far as I understand it, the current way of omitting the timezone information from datetimes is the default way Clickhouse expects these values to be inserted.

Clickhouse can't handle timezone information in datetime strings unless they are properly ISO 8601 formatted and the date_time_input_format query setting is set to best_effort.

I just personally prefer having this information present at all time and not messing around with application side conversion before passing the values to Clickhouse, so I opt in to passing this option every time I insert data or query datetime related values. If I'm not mistaken, this can and should only be a userland decision.

[simPod]

There's timezone param in ValueFormatter that ensures timezone is not stripped on insertion.

PhpClickHouseClient/src/Sql/ValueFormatter.php

Line 27 in bb30986

final readonly class ValueFormatter

I planned to consolidate ValueFormatter and ParamValueConverterRegistry

[simPod]

WDYT about #287?

[filecage]

WDYT about #287?

I have added a comment to that PR: #287 (comment)