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)

• 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

  • Chronograph
  • DaysEnum and MonthsEnum
  • MySqlDateTime
  • Clock and DateTime Providers (Dependency Injection)

• Testing

• Contributing

• Changelog & Compatibility

• License

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

use JoeFallon\PhpTime\Chronograph;

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

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

use JoeFallon\PhpTime\MySqlDateTime;

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

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

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

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

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();

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'

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'

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.

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

Contributions are welcome. Suggested workflow:

1. Fork the repository
2. Create a feature branch
3. Add tests covering new or changed behavior
4. Run the test suite and ensure all tests pass
5. 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

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

MIT License — see the LICENSE file for details

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