PHPackages                             thomas-institut/timestring - 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. thomas-institut/timestring

ActiveLibrary

thomas-institut/timestring
==========================

A class to deal with MySQL datetime strings with microseconds

v2.1.1(1y ago)0113[1 PRs](https://github.com/thomas-institut/timestring/pulls)1GPL-3.0-or-laterPHPPHP >=8.3CI passing

Since Jan 22Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/thomas-institut/timestring)[ Packagist](https://packagist.org/packages/thomas-institut/timestring)[ RSS](/packages/thomas-institut-timestring/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (7)Dependencies (2)Versions (9)Used By (1)

thomas-institut/timestring
==========================

[](#thomas-instituttimestring)

[![Latest Stable Version](https://camo.githubusercontent.com/bf3ae046552d14398ffa1d6aefab88568d816e1088b1b0baa01d943479aed2c9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74686f6d61732d696e7374697475742f74696d65737472696e673f6c6162656c3d537461626c65)](https://camo.githubusercontent.com/bf3ae046552d14398ffa1d6aefab88568d816e1088b1b0baa01d943479aed2c9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74686f6d61732d696e7374697475742f74696d65737472696e673f6c6162656c3d537461626c65)[![GitHub License](https://camo.githubusercontent.com/c5beaaf7aac49f3c3c2e6fae54a28d0d2f93abb72894e3c991a39f2f02f3c23e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f74686f6d61732d696e7374697475742f74696d65737472696e67)](https://camo.githubusercontent.com/c5beaaf7aac49f3c3c2e6fae54a28d0d2f93abb72894e3c991a39f2f02f3c23e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f74686f6d61732d696e7374697475742f74696d65737472696e67)

[![Dynamic JSON Badge](https://camo.githubusercontent.com/56334ea58da8025bdc6229ae94beeab95f35bc6306363443b96cf887b1352cd5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f64796e616d69632f6a736f6e3f75726c3d68747470732533412532462532467261772e67697468756275736572636f6e74656e742e636f6d25324674686f6d61732d696e73746974757425324674696d65737472696e672532467265667325324668656164732532466d6173746572253246636f6d706f7365722e6a736f6e2671756572793d2532342e726571756972652e706870266c6162656c3d50485025323056657273696f6e)](https://camo.githubusercontent.com/56334ea58da8025bdc6229ae94beeab95f35bc6306363443b96cf887b1352cd5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f64796e616d69632f6a736f6e3f75726c3d68747470732533412532462532467261772e67697468756275736572636f6e74656e742e636f6d25324674686f6d61732d696e73746974757425324674696d65737472696e672532467265667325324668656164732532466d6173746572253246636f6d706f7365722e6a736f6e2671756572793d2532342e726571756972652e706870266c6162656c3d50485025323056657273696f6e)

A TimeString is an immutable object that holds a string with a MySQL datetime value with microseconds, e.g., `'1999-12-31 23:59:50.123456'`. No timezone information is stored in the class.

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

[](#installation)

`composer require thomas-institut/timestring`

Usage
-----

[](#usage)

### Constructor

[](#constructor)

TimeString objects can be constructed from strings, float or integer timestamps, or DateTime objects.

Strings given to the constructor can be partial or complete MySQL datetime values or any format accepted by PHP's DateTime class. Empty strings are not allowed.

```
$ts = new TimeString('1999-12-31 23:59:50.123456');
// inner value is '1999-12-31 23:59:50.123456'

$ts = new TimeString('1999-12-31 23:59:50');
// inner value is '1999-12-31 23:59:50.000000'

$ts = new TimeString('1999-12-31');
// inner value is '1999-12-31 00:00:00.000000'

$ts = new TimeString('December 31, 1999');
// inner value is '1999-12-31 00:00:00.000000'

// but
$ts = new TimeString('');
// throws InvalidArgumentException
```

Floats and integers are understood as Unix timestamps. An additional parameter can be given to specify the timezone:

```
date_default_timezone_set('UTC');

$ts = new TimeString(1745307389);
// inner value is '2025-04-22 07:36:29.000000

$ts = new TimeString(1745307389.123456, 'Europe/Berlin');
// inner value is '2025-04-22 09:36:29.123456
```

DateTime objects are also accepted:

```
$dt = new DateTime('December 31,1999');

$ts = new TimeString($dt);
// inner value is '1999-12-31 00:00:00.000000'
```

### Casting and Formatting

[](#casting-and-formatting)

A TimeString object can be cast into a string or formatted using PHP's DateTime interface formats (see )

```
$timeString = new TimeString('1999-12-31 23:59:50.123456');

$timeString->toString()
// '1999-12-31 23:59:50.123456'

strval($timeString)
// '1999-12-31 23:59:50.123456'

$timeString->format('d F Y')
// '31 December 1999'
```

TimeString objects can be transformed into other types:

```
$timeString->toTimestamp(); // a float timestamp
$timeString->toDateTime(); // a DateTime object
$timeString->toDateTime('Asia/Tokyo'); // a DateTime object with a given TZ
```

It is also possible to create a new TimeString object in a different timezone:

```
$newTimestring = $someTimeString->toNewTimeZone($newTimeZone);
```

TimeString objects can be also created from and converted to compact strings with only numbers:

```
$timeString = new TimeString('1999-12-31 23:59:50.123456');

$timeString->toCompactString();
// '19991231235950123456'

$ts = TimeString::fromCompactString('19991231235950123456');
$ts->toString();
// '1999-12-31 23:59:50.123456'
```

### Factory Methods

[](#factory-methods)

The following factory methods are also provided:

```
$ts = TimeString::now();   // the current time in PHP's default timezone
$ts = TimeString::now('Europe/Berlin'); // the current time in Berlin

$ts = TimeString::fromTimestamp(1736341528); // from any int or float timestamp
$ts = TimeString::fromTimestamp(1736341528, 'America/Costa_Rica'); // with time zone
$ts = TimeString::fromString('today'); // from any string that DateTime can parse
$ts = TimeString::fromDateTime($someDateTimeObject);

// or let TimeString figure it out
$ts = TimeString::fromVariable($someVariable);
```

### Comparison

[](#comparison)

The class provides comparison functions:

```
$timeString = new TimeString('1999-12-31 23:59:50.123456');
$timeStringWithSameValue = clone $timeString;

TimeString::equals($timestring, $timeStringWithSameValue);
// true
TimeString::cmp($timestring, $timeStringWithSameValue);
// 0

$laterTimeString = new TimeString('2000-12-31 23:59:50.123456');

TimeString::equals($timestring, $laterTimeString);
// false
TimeString::cmp($timestring, $laterTimeString);
// 1

$earlierTimeString = new TimeString('1998-12-31 23:59:50.123456');

TimeString::equals($timestring, $laterTimeString);
// false
TimeString::cmp($timestring, $laterTimeString);
// -1
```

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance71

Regular maintenance activity

Popularity12

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity77

Established project with proven stability

 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 ~319 days

Recently: every ~468 days

Total

7

Last Release

382d ago

Major Versions

v1.3 → v2.02025-01-08

PHP version history (3 changes)v1.0.1PHP >=7.1

v1.3PHP >=8.1

v2.1PHP >=8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/bdaa55fa14e6465a3a36c0814583c3cde96e14b6f556d01d866065d0bcb42b3e?d=identicon)[rafaelnajera](/maintainers/rafaelnajera)

---

Top Contributors

[![rafaelnajera](https://avatars.githubusercontent.com/u/17843226?v=4)](https://github.com/rafaelnajera "rafaelnajera (14 commits)")

---

Tags

data

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/thomas-institut-timestring/health.svg)

```
[![Health](https://phpackages.com/badges/thomas-institut-timestring/health.svg)](https://phpackages.com/packages/thomas-institut-timestring)
```

###  Alternatives

[fakerphp/faker

Faker is a PHP library that generates fake data for you.

3.9k358.5M3.5k](/packages/fakerphp-faker)[nelmio/alice

Expressive fixtures generator

2.5k43.4M132](/packages/nelmio-alice)[dflydev/dot-access-data

Given a deep data structure, access data by dot notation.

718359.1M86](/packages/dflydev-dot-access-data)[doctrine/mongodb-odm

PHP Doctrine MongoDB Object Document Mapper (ODM) provides transparent persistence for PHP objects to MongoDB.

1.1k23.3M299](/packages/doctrine-mongodb-odm)[sonata-project/exporter

Lightweight Exporter library

44920.9M35](/packages/sonata-project-exporter)[theofidry/alice-data-fixtures

Nelmio alice extension to persist the loaded fixtures.

32528.5M69](/packages/theofidry-alice-data-fixtures)

PHPackages © 2026

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