PHPackages                             boruta/timebase - 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. boruta/timebase

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

boruta/timebase
===============

Flat file database for storage any data as events in timeline and finding it for a given timestamp.

0.1(5y ago)113MITPHPPHP >=7.3

Since Jan 30Pushed 5y ago1 watchersCompare

[ Source](https://github.com/borutainfo/timebase)[ Packagist](https://packagist.org/packages/boruta/timebase)[ RSS](/packages/boruta-timebase/feed)WikiDiscussions main Synced 6d ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

TimeBase
========

[](#timebase)

[![Tests Status](https://camo.githubusercontent.com/4b605aac3860a83c869c6185b6eed7359399a3b98346ac85db6fffd670a527d3/68747470733a2f2f62616467656e2e6e65742f62616467652f74657374732f737563636573732f677265656e)](https://camo.githubusercontent.com/4b605aac3860a83c869c6185b6eed7359399a3b98346ac85db6fffd670a527d3/68747470733a2f2f62616467656e2e6e65742f62616467652f74657374732f737563636573732f677265656e)

Flat file database for storage any data as events in timeline and finding it for a given timestamp.

### Table of contents

[](#table-of-contents)

1. [Description](#description)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Usage](#usage)
    1. [Quick introduction](#quick-introduction)
    2. [Details](#details)
        1. [Extra logger in constructor](#extra-logger-in-constructor)
        2. [Data types](#data-types)
        3. [Setting the storage namespace](#setting-the-storage-namespace)
        4. [Inserting data for specific timestamp](#inserting-data-for-specific-timestamp)
        5. [Searching data for specific timestamp](#searching-data-for-specific-timestamp)
        6. [Getting multiple records with the same timestamp](#getting-multiple-records-with-the-same-timestamp)
        7. [Searching strategies](#searching-strategies)
5. [Tests](#tests)

Description
-----------

[](#description)

The data are stored in files, with the possibility of using multi-level namespaces - in this case, the files are stored in subdirectories. Each day is stored in a separate file named `YYYY-MM-DD.tb`.

The data records are searched using a binary search algorithm, so it's quick and doesn't require loading the entire file into memory. Each record is one line in file, in format `{timestamp}/{data}` (`data` is result of `base64_encode(json_encode(...))`). The records are sorted, and you can add multiple records for one timestamp - they are saved and returned in the order they were added.

There are many use cases for such a database, e.g. storing stock exchange data (volumes, price values etc.) for trading strategy backtesting.

Requirements
------------

[](#requirements)

Package requires PHP >= 7.3 and ext-json installed.

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

[](#installation)

Install the library using Composer. Please read the [Composer Documentation](https://getcomposer.org/doc/01-basic-usage.md) if you are unfamiliar with Composer or dependency managers in general.

```
composer require boruta/timebase
```

Usage
-----

[](#usage)

### Quick introduction

[](#quick-introduction)

Creating database instance. First constructor argument is a path where to store database files.

```
$timebase = new Boruta\Timebase\Timebase(__DIR__ . '/database/');
```

Inserting data (for current timestamp) :

```
$timebase->insert()->set('test')->execute();
```

Getting last inserted data (last record):

```
$result = $timebase->search()->execute();
```

You will get array as result, with keys `timestamp` and `value`:

```
array(2) {
  ["timestamp"]=>
  int(1612022907)
  ["value"]=>
  string(4) "test"
}
```

### Details

[](#details)

#### Extra logger in constructor

[](#extra-logger-in-constructor)

You can optionally give the second argument which is a logger object, compatible with `Psr\Log\LoggerInterface`. The application append logs only in case of errors.

```
$timebase = new Boruta\Timebase\Timebase(__DIR__ . '/database/', $logger);
```

#### Data types

[](#data-types)

The data can be of any native type, e.g. `int`, `string`, `array`. When searching for data, they will be of the same type.

```
$timebase->insert()
    ->set(123) // or ->set('test') or ->set(['test' => 123]) etc.
    ->execute();
```

#### Setting the storage namespace

[](#setting-the-storage-namespace)

You can store your data in different storages on many levels. Please use the method `->storage(array $storage)` to set this.

Examples of inserting data into specific storage:

```
$timebase->insert()
    ->storage(['test']) // storage path: __DIR__ . '/database/test/'
    ->set('test')
    ->execute();
```

```
$timebase->insert()
    ->storage(['level0', 'level1']) // storage path: __DIR__ . '/database/level0/level1/'
    ->set('test')
    ->execute();
```

Examples of reading data from specific storage:

```
$result = $timebase->search()
    ->storage(['test']) // storage path: __DIR__ . '/database/test/'
    ->execute();
```

```
$result = $timebase->search()
    ->storage(['level0', 'level1']) // storage path: __DIR__ . '/database/level0/level1/'
    ->execute();
```

#### Inserting data for specific timestamp

[](#inserting-data-for-specific-timestamp)

To add data for a given timestamp (not the current) use the method `->timestamp(int $timestamp)`. Example:

```
$timebase->insert()
    ->timestamp(1612022907)
    ->set('test')
    ->execute();
```

#### Searching data for specific timestamp

[](#searching-data-for-specific-timestamp)

To find a record for a specific timestamp use the method `->timestamp(int $timestamp)` during search query:

```
$result = $timebase->search()
    ->timestamp(1612022907)
    ->execute();
```

In the default strategy, you will get one record that is closest to the timestamp you entered.

#### Getting multiple records with the same timestamp

[](#getting-multiple-records-with-the-same-timestamp)

If you have more than one record with the same timestamp you can retrieve them using the `->all()` method.

```
$result = $timebase->search()
    ->timestamp(1612022907)
    ->all()
    ->execute();
```

In the result array there will be an additional key `all` containing all records for given timestamp, in the order in which they were added:

```
array(3) {
  ["timestamp"]=>
  int(1612012606)
  ["value"]=>
  string(4) "test"
  ["all"]=>
  array(2) {
    [0]=>
    string(4) "test"
    [1]=>
    string(4) "test"
  }
}
```

#### Searching strategies

[](#searching-strategies)

**Nearest** (default)

The default strategy returns the record with the nearest timestamp to the given one. Usage (is not necessary as it is the default):

```
$result = $timebase->search()
    ->strategy(\Boruta\Timebase\Common\Constant\SearchStrategyConstant::NEAREST)
    ->timestamp(1612022907)
    ->execute();
```

If the time distance is the same for two records, you will get the earlier one.

**Exact**

If there is no record for the timestamp you provided, you will get `null` value. There must be a record in the database with exactly the same timestamp.

```
$result = $timebase->search()
    ->strategy(\Boruta\Timebase\Common\Constant\SearchStrategyConstant::EXACT)
    ->timestamp(1612022907)
    ->execute();
```

**Earlier**

If there is no record for the timestamp you entered, you will get the closest one before that timestamp or `null`.

```
$result = $timebase->search()
    ->strategy(\Boruta\Timebase\Common\Constant\SearchStrategyConstant::EARLIER)
    ->timestamp(1612022907)
    ->execute();
```

**Later**

If there is no record for the timestamp you entered, you will get the closest one after that timestamp or `null`.

```
$result = $timebase->search()
    ->strategy(\Boruta\Timebase\Common\Constant\SearchStrategyConstant::LATER)
    ->timestamp(1612022907)
    ->execute();
```

Tests
-----

[](#tests)

To run the tests in the package, execute the following command:

```
vendor/bin/phpunit tests
```

After a while you will get the result, example:

```
OK (31 tests, 526577 assertions)

```

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

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

Unknown

Total

1

Last Release

1933d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/85cc760c4ab74fc51cc20ead906f7a85974ae51b59a0df460f8d3e7f56635f8f?d=identicon)[Boruta](/maintainers/Boruta)

---

Top Contributors

[![borutainfo](https://avatars.githubusercontent.com/u/16668386?v=4)](https://github.com/borutainfo "borutainfo (10 commits)")

---

Tags

binary-searchdatabaseeventsfile-databaseflat-databasephptimelinetimestamp

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/boruta-timebase/health.svg)

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

###  Alternatives

[doctrine/dbal

Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.

9.7k578.4M5.6k](/packages/doctrine-dbal)[kimai/kimai

Kimai - Time Tracking

4.6k7.4k1](/packages/kimai-kimai)[cycle/database

DBAL, schema introspection, migration and pagination

64690.9k31](/packages/cycle-database)[guikingone/scheduler-bundle

A Symfony bundle that allows to schedule and create repetitive tasks

114217.4k](/packages/guikingone-scheduler-bundle)[symfony/ai-store

Low-level abstraction for storing and retrieving documents in a vector store.

19292.4k53](/packages/symfony-ai-store)[tommyknocker/pdo-database-class

Framework-agnostic PHP database library with unified API for MySQL, MariaDB, PostgreSQL, SQLite, MSSQL, and Oracle. Query Builder, caching, sharding, window functions, CTEs, JSON, migrations, ActiveRecord, CLI tools, AI-powered analysis. Zero external dependencies.

845.7k](/packages/tommyknocker-pdo-database-class)

PHPackages © 2026

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