README

Lightweight, well-tested utilities for working with time in PHP — designed for simplicity, clarity, and testability. Useful when you need small, dependable helpers like a high-resolution chronograph, readable day/month enums, or MySQL-compatible timestamps.

This library favors explicit, testable APIs and minimal dependencies. It's not a full-featured date/time framework — instead, it provides pragmatic, focused tools that many PHP apps need.

Project: JoeFallon/phptime
License: MIT
PHP Requirement: 7.4+ (compatible with PHP 8.x)

Why Use This Library?

Small, focused utilities you can drop into any project
Dependency-injection friendly for deterministic tests
Includes a test suite (PHPUnit 9.6 compatible for PHP 7.4)
Clear, well-documented API for common use-cases (timestamps, enums, timers)

Installation
Quick Start
API Reference
Testing
Contributing
Changelog & Compatibility
License

Installation

Install via Composer (recommended):

composer require joefallon/phptime

If you're a library author, add it to your composer.json as a dependency and run:

composer install
composer update

Quick Start

Chronograph (Measure Elapsed Time)

use JoeFallon\PhpTime\Chronograph;

$timer = new Chronograph();
$timer->start();
// ... work ...
$timer->stop();

echo $timer->getElapsedMilliseconds(); // e.g. 12.3

MySQL DATETIME Strings

use JoeFallon\PhpTime\MySqlDateTime;

$now = MySqlDateTime::nowTimestamp(); 
// e.g. "2025-10-13 14:05:33"

Days and Months Enum Helpers

use JoeFallon\PhpTime\DaysEnum;
use JoeFallon\PhpTime\MonthsEnum;

$days = DaysEnum::all();
$months = MonthsEnum::all();

if (MonthsEnum::isValid('Feb')) { /* ... */ }

API Reference

Chronograph

Namespace: JoeFallon\PhpTime\Chronograph

A high-resolution timer for measuring elapsed time.

Methods:

start() — start or restart the timer
stop() — stop the timer (throws LogicException if not started)
reset() — clear start and stop times
isRunning() — check if timer is running
getElapsedSeconds() — elapsed seconds (float)
getElapsedMilliseconds() — elapsed milliseconds (float)

Example with Dependency Injection:

use JoeFallon\PhpTime\Chronograph;
use JoeFallon\PhpTime\SystemClock;

$clock = new SystemClock();
$chrono = new Chronograph($clock);
$chrono->start();
// ...
$chrono->stop();

echo $chrono->getElapsedMilliseconds();

DaysEnum and MonthsEnum

Namespaces: JoeFallon\PhpTime\DaysEnum, JoeFallon\PhpTime\MonthsEnum

Value-object style enums exposing full-name constants and short aliases (e.g., MonthsEnum::JANUARY and MonthsEnum::JAN) with helper methods:

all() — returns all values
isValid($value) — check if value is valid
indexOf($value) — get index of value
fromIndex($index) — get value from index

Example:

use JoeFallon\PhpTime\MonthsEnum;

$all = MonthsEnum::all();        // ['January', 'February', ...]
$index = MonthsEnum::indexOf('Mar'); // 2
$name = MonthsEnum::fromIndex(11);   // 'December'

MySqlDateTime

Namespace: JoeFallon\PhpTime\MySqlDateTime

Utility for producing MySQL-ready DATETIME strings (Y-m-d H:i:s) with optional microseconds.

Primary Static Methods:

nowTimestamp(?DateTimeProviderInterface $provider = null): string — current timestamp
nowTimestampWithMicroseconds(?DateTimeProviderInterface $provider = null): string — timestamp with microseconds
nowUtcTimestamp(?DateTimeProviderInterface $provider = null, bool $withMicro = false) — UTC timestamp
fromDateTime(DateTimeInterface $dt, bool $withMicro = false): string — format any DateTimeInterface
fromTimestamp(int $seconds, int $microseconds = 0, bool $utc = false, bool $withMicro = false): string — from epoch + microseconds
validate(string $value, bool $allowMicro = false): bool — validate MySQL DATETIME string

Example (Production):

use JoeFallon\PhpTime\MySqlDateTime;

$now = MySqlDateTime::nowTimestamp();
// Insert into DB: created_at = $now

Example (Testing with Deterministic Provider):

use JoeFallon\PhpTime\MySqlDateTime;
use JoeFallon\PhpTime\DateTimeProviderInterface;
use DateTimeImmutable;
use DateTimeZone;

$provider = new class implements DateTimeProviderInterface {
    public function now(): \DateTimeInterface
    {
        return new DateTimeImmutable('2001-01-02 03:04:05', new DateTimeZone('UTC'));
    }
};

MySqlDateTime::nowTimestamp($provider); // '2001-01-02 03:04:05'

Clock and DateTime Providers (Dependency Injection)

For deterministic testing, the library provides interfaces and default system implementations:

ClockInterface / SystemClock — used by Chronograph (returns float seconds)
DateTimeProviderInterface / SystemDateTimeProvider — used by MySqlDateTime (returns DateTimeInterface)

Inject custom implementations (fake clocks, controlled time sources) for predictable behavior in tests.

Testing

The project includes a PHPUnit test suite. Run tests locally:

composer install
./vendor/bin/phpunit -c phpunit.xml.dist

Windows users: vendor\bin\phpunit -c phpunit.xml.dist

Contributing

Contributions are welcome. Suggested workflow:

Fork the repository
Create a feature branch
Add tests covering new or changed behavior
Run the test suite and ensure all tests pass
Open a pull request with a clear description

Coding Guidelines:

Keep the API small and explicit
Use dependency injection for clock/time providers to enable deterministic tests
Add unit tests for new behavior and edge cases

Changelog & Compatibility

PHP 7.4+ supported
PHPUnit 9.6 for PHP 7.4
Test suite maintained for backward compatibility

License

MIT License — see the LICENSE file for details

Support & Contact

If you encounter bugs or want enhancements, open an issue on the project repository. The test suite contains usage examples and edge-case handling.

Enjoy, and thanks for using phptime! — Joe Fallon

joefallon / phptime

Maintainers

Details