Use Redis Time Series in PHP!
composer require palicao/php-redis-time-series
The library is tested against:
- PHP 7.2, 7.3, 7.4, 8.0
- RedisTimeSeries 1.4.10 (but it should work with any 1.4 version)
In order to use RedisTimeSeries 1.2 please use version 2.1.1 of this library.
$ts = new TimeSeries(
new RedisClient(
new Redis(),
new RedisConnectionParams($host, $port)
)
);
TimeSeries::create(string $key, ?int $retentionMs = null, array $labels = []): void
Creates a key, optionally setting a retention time (in milliseconds) and some labels.
See https://oss.redislabs.com/redistimeseries/commands/#tscreate.
TimeSeries::alter(string $key, ?int $retentionMs = null, array $labels = []): void
Modifies an existing key's retention time and/or labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsalter.
TimeSeries::add(Sample $sample, ?int $retentionMs = null, array $labels = []): Sample
Adds a sample.
If the key was not explicitly created, it's possible to set retention and labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsadd.
Examples:
$sample = $ts->add(new Sample('myKey', 32.10), 10, [new Label('myLabel', 'myValue')]);Adds a sample tomyKeyat the current timestamp (time of the redis server) and returns it (complete with dateTime).$sample = $ts->add(new Sample('myKey', 32.10, new DateTimeImmutable()), 10, [new Label('myLabel', 'myValue')]);Adds a sample tomyKeyat a given datetime and returns it.
Please notice that RedisTimeSeries only allows to add samples in order (no sample older than the latest is allowed)
TimeSeries::addMany(array $samples): array
Adds several samples.
As usual, if no timestamp is provided, the redis server current time is used. Added samples are returned in an array.
See https://oss.redislabs.com/redistimeseries/commands/#tsmadd.
TimeSeries::incrementBy(Sample $sample, ?int $resetMs = null, ?int $retentionMs = null, array $labels = []): void
TimeSeries::decrementBy(Sample $sample, ?int $resetMs = null, ?int $retentionMs = null, array $labels = []): void
Add a sample to a key, incrementing or decrementing the last value by an amount specified in $sample.
The value can be optionally reset after $resetMs milliseconds.
Similarly to add, if the command is used on a non-existing key, it's possible to set retention and labels.
See https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby.
TimeSeries::createRule(string $sourceKey, string $destKey, AggregationRule $rule): void
Creates an aggregation rule which applies the given $rule to $sourceKey in order to populate $destKey.
Notice that both key must already exist otherwise the command will fail.
See https://oss.redislabs.com/redistimeseries/commands/#tscreaterule.
Example:
$ts->createRule('source', 'destination', new AggregationRule(AggregationRule::AVG, 10000), will populate thedestinationkey by averaging the samples contained insourceover 10 second buckets.
TimeSeries::deleteRule(string $sourceKey, string $destKey): void
Deletes an existing aggregation rule.
See https://oss.redislabs.com/redistimeseries/commands/#tsdeleterule.
TimeSeries::range(string $key, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): Sample[]
Retrieves samples from a key. It's possible to limit the query in a given time frame (passing $from and $to),
to limit the retrieved amount of samples (passing $count), and also to pre-aggregate the results using a $rule.
The flag $reverse will return the results in reverse time order.
See https://oss.redislabs.com/redistimeseries/commands/#tsrange.
TimeSeries::multiRange(Filter $filter, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): Sample[]
TimeSeries::multiRangeWithLabels(Filter $filter, ?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?int $count = null, ?AggregationRule $rule = null, bool $reverse = false): SampleWithLabels[]
Similar to range, but instead of querying by key, queries for a specific set of labels specified in $filter.
multiRangeWithLabels will return an array of SampleWithLabels instead of simple Samples.
The flag $reverse will return the results in reverse time order.
See https://oss.redislabs.com/redistimeseries/commands/#tsmrange.
TimeSeries::getLastSample(string $key): Sample
Gets the last sample for a key.
See https://oss.redislabs.com/redistimeseries/commands/#tsget.
TimeSeries::getLastSamples(Filter $filter): Sample[]
Gets the last sample for a set of keys matching a given $filter.
See https://oss.redislabs.com/redistimeseries/commands/#tsmget.
TimeSeries::info(string $key): Metadata
Gets useful metadata for a given key.
See https://oss.redislabs.com/redistimeseries/commands/#tsinfo.
getKeysByFilter(Filter $filter): string[]
Retrieves the list of keys matching a given $filter.
See https://oss.redislabs.com/redistimeseries/commands/#tsqueryindex.
You can manipulate your RedisConnectionParams using the following methods:
RedisConnectionParams::setPersistentConnection(bool $persistentConnection)enable/disable a persistent connectionRedisConnectionParams::setTimeout(int $timeout)connection timeout in secondsRedisConnectionParams::setRetryInterval(int $retryInterval)retry interval in secondsRedisConnectionParams::setReadTimeout(float $readTimeout)read timeout in seconds
A Filter is composed of multiple filtering operations. At least one equality operation must be provided (in the
constructor). Adding filtering operations can be chained using the method add.
Examples:
$f = (new Filter('label1', 'value1'))->add('label2', Filter::OP_EXISTS);filters items which have label1 = value1 and have label2.$f = (new Filter('label1', 'value1'))->add('label2', Filter::OP_IN, ['a', 'b', 'c']);filters items which have label1 = value1 and where label2 is one of 'a', 'b' or 'c'.
For local testing you can use the provided docker-compose.yml file, which will create a PHP container (with the redis
extension pre-installed), and a redis container (with Redis Time Series included).
Thanks Mrkisha for the precious contributions.