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 yesterday

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

23

—

LowBetter than 26% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity36

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

527d 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

[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k117.2M118](/packages/jdorn-sql-formatter)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M87](/packages/propel-propel1)[pgvector/pgvector

pgvector support for PHP

198741.5k12](/packages/pgvector-pgvector)[jfelder/oracledb

Oracle DB driver for Laravel

11518.4k](/packages/jfelder-oracledb)

PHPackages © 2026

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