Download the PHP package joefallon/phptime without Composer

phptime

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)

Table of Contents

• Installation
• Quick Start

• API Reference

  • Chronograph
  • DaysEnum and MonthsEnum
  • MySqlDateTime
  • Clock and DateTime Providers (Dependency Injection)
• Testing
• Contributing
• Changelog & Compatibility
• License

Installation

Install via Composer (recommended):

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

Quick Start

Chronograph (Measure Elapsed Time)

MySQL DATETIME Strings

Days and Months Enum Helpers

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:

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:

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):

Example (Testing with Deterministic Provider):

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:

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

Contributing

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

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