PHPackages                             cstuder/myts - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. cstuder/myts

ActiveLibrary[Database & ORM](/categories/database)

cstuder/myts
============

Keeping time series data in relational databases

v0.2.1(1y ago)16MITPHP

Since Feb 22Pushed 1y ago1 watchersCompare

[ Source](https://github.com/cstuder/MyTS)[ Packagist](https://packagist.org/packages/cstuder/myts)[ RSS](/packages/cstuder-myts/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (6)Used By (0)

MyTS
====

[](#myts)

Simple PHP package for keeping time series data in relational databases.

"For if all you have is a MySQL instance, everything looks like relational data."

[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://camo.githubusercontent.com/b0f360a81068393f513b910699d643a2e8b05134f22229d0bf417734c17fed2e/68747470733a2f2f7777772e7265706f7374617475732e6f72672f6261646765732f6c61746573742f7769702e737667)](https://www.repostatus.org/) [![Automated tests](https://github.com/cstuder/MyTS/actions/workflows/test.yml/badge.svg)](https://github.com/cstuder/MyTS/actions/workflows/test.yml)

Overview
--------

[](#overview)

This library is used to store meteorolgical time series measured at weather stations for the [api.existenz.ch](https://api.existenz.ch) project. It is a simple and lightweight solution for storing time series data in a relational database.

First create some locations with `createLocation('locationname')`, then some parameters with `createParameter('parametername', 'unit')`.

Insert values with `insertValue('locationname', 'parametername', $timestamp, $value)`.

Retrieve values with `getValues()` or `getLatestValues()` and you will get a `\cstuder\ParseValueholder\Row` filled with `\cstuder\ParseValueholder\Value` objects:

```
$row->getValues();

->

[
    Value {
        location => 'locationname',
        parameter => 'parametername',
        timestamp => 1234567890,
        value => '1.23'
    }
]
```

### Setup database

[](#setup-database)

The package uses a connection to a MySQL compatible database (using `MyTS::MyTSMySQLFactory` or `MyTS::MyTSFromDSNFactory`) and a timeseries name to create four tables:

- `myts_timeseriesname_loc` for locations and their metadata
- `myts_timeseriesname_par` for parameters, their unit and metadata
- `myts_timeseriesname_val` for values
- `myts_timeseriesname_latest` for latest values
- Optional: `myts_timeseriesname_view` with an aggregated view

The values default to to the type `FLOAT`, but can be changed to any other time at the time of creation with `createDatabaseTables()`.

First create some locations with `createLocation('locationname')`, then some parameters with `createParameter('parametername', 'unit')`. Both methods accept an optional key-value array which is serialized into the database.

To update a location or parameter, simply call `createLocation()` or `createParameter()` again with the same name and updated metadata. You cannot change the name of a location or parameter.

### Insert values

[](#insert-values)

Insert values with `insertValue('locationname', 'parametername', $timestamp, $value)`. The timestamp is a Unix timestamp. Location and parameter names are case sensitive. The method will return `true` if successful. It will throw an exception if the insertion fails (I.e. if the location or parameter doesn't exist). Set the last parameter to `true` fail silently and just return `false`.

To update a previous values, the same `insertValue()` method can be used.

The convenience methods `insertValueObject()` and `insertValueRow()` can be used to insert values from a `Value` object or a `Row` object respectively.

### Retrieve values

[](#retrieve-values)

Use `getValues()` to retrieve values from the timeseries. The method accepts optional start and end times. Filtering by locations and parameters is also available (By default unknown location or parameter names will be ignored, but this can by changed by setting the parameter `$failSilenty` to `false`).

If no location and/or parameter names are given, all locations and/or parameters respectively will be returned.

For quickly retrieving the latest values, use `getLatestValues()`. It accepts optional location and parameter names.

Data is returned as a `\cstuder\ParseValueholder\Row` which is filled by an array of `\cstuder\ParseValueholder\Value` objects:

```
$row->getValues();

->

[
    Value {
        location => 'locationname',
        parameter => 'parametername',
        timestamp => 1234567890,
        value => '1.23'
    }
]
```

### Maintenance

[](#maintenance)

The method `deleteValuesOlderThan()` indiscriminately deletes all values older than a given timestamp. Use with caution.

### Limitations

[](#limitations)

- Location and parameter names are case sensitive and can only be 128 characters long.
- There is no bulk insert (Which would be much faster when importing large datasets).
- It could work with other database engines (MariaDB etc.) too, but is not tested. (Uses the PDO library internally.)
- Databases typically return all fields as strings in PHP.

Usage
-----

[](#usage)

Sample usage code (Runnable version in [`sample_usage.php`](docs/sample_usage.php))

```
// Connection: Timeseries name, server, user, password, database, optional port (Default: 3306)
$myTS = MyTS::MyTSMySQLFactory('test', 'localhost', 'testuser', 'testpassword', 'testdb');

// Create database tables (Only if they don't exist yet), plus an additional info view
$myTS->createDatabaseTables('DECIMAL(8,2)', true);

// Create locations with optional metadata
$myTS->createLocation('here');
$myTS->createLocation('there', ['where' => 'exactly there']);

// Update locations with metadata
$myTS->createLocation('here', ['where' => 'not there']);

// Show locations
var_dump($myTS->getAllLocations());

// Create parameters with optional units and optional metadata
$myTS->createParameter('aaa');
$myTS->createParameter('bbb', 'potatoes');
$myTS->createParameter('ccc', NULL, ['si' => FALSE]);

// Update parameter
$myTS->createParameter('ccc', 'kg', ['si' => TRUE]);

// Show parameters
var_dump($myTS->getAllParameters());

// Insert values (Location and parameters are case sensitive)
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:00:00'), 1);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:04:00'), -3);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:02:00'), 1.567);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:03:00'), 1.56789);
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:01:00'), 1.5);
$myTS->insertValue('there', 'bbb', strtotime('2018-01-01 00:01:00'), 1.51);
$myTS->insertValue('there', 'aaa', strtotime('2018-01-01 00:01:00'), 1.49);

// Update values
$myTS->insertValue('here', 'aaa', strtotime('2018-01-01 00:00:00'), -1);

// Insert value in unknown location/parameter silently
var_dump($myTS->insertValue('xxyyzz', 'xxyyzz', strtotime('2018-01-01 00:00:00'), 1, true));

// Insert value in unknown location/parameter noisily
try {
    $myTS->insertValue('xxyyzz', 'xxyyzz', strtotime('2018-01-01 00:00:00'), 1, false);
} catch (Exception $e) {
    var_dump($e);
}

// Get all values in this timeseries
var_dump($myTS->getValues());

// Get subset of values
var_dump($myTS->getValues(null, null, 'here'));
var_dump($myTS->getValues(null, null, 'asbasdf')); // Unknown location, fails silently

// Get latest values
var_dump($myTS->getLatestValues());

// Get subset of latest values
var_dump($myTS->getLatestValues('there'));
var_dump($myTS->getLatestValues(null, 'bbb'));
var_dump($myTS->getLatestValues('asbasdf')); // Unknown location, fails silently
```

Installation
------------

[](#installation)

`composer require cstuder/myts`

Testing
-------

[](#testing)

`composer run test`

Requires a running MySQL compatible database on localhost/127.0.0.1 with the following credentials: `testuser`, `testpassword`, `testdb`.

Can be overwritten by a valid DSN including username and password in the environment variable `MYTS_DSN`, for example:

`mysql:host=localhost;port=3306;dbname=testdb;user=testuser;password=testpassword;charset=utf8`

Release
-------

[](#release)

See [CHANGELOG.md](CHANGELOG.md) for the release history.

1. Add changes to the [changelog](CHANGELOG.md).
2. Create a new tag `vX.X.X`.
3. Push.

License
-------

[](#license)

MIT

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance42

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~111 days

Total

4

Last Release

479d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/187a50291ddb9eb756891e4e54da3c856075ac55f776b74c5fa324f2074d193d?d=identicon)[cstuder](/maintainers/cstuder)

---

Top Contributors

[![cstuder](https://avatars.githubusercontent.com/u/288493?v=4)](https://github.com/cstuder "cstuder (22 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cstuder-myts/health.svg)

```
[![Health](https://phpackages.com/badges/cstuder-myts/health.svg)](https://phpackages.com/packages/cstuder-myts)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)