Download the PHP package tiny-blocks/time without Composer

Time

• Overview
• Installation
• How to use
  • Instant
    • Creating from the current moment
    • Creating from a string
    • Creating from a database timestamp
    • Creating from Unix seconds
    • Adding and subtracting time
    • Measuring distance between instants
    • Comparing instants
    • Emitting with sub-second precision
  • Duration
    • Creating durations
    • Arithmetic
    • Division
    • Comparing durations
    • Converting to other units
  • Period
    • Creating from two instants
    • Creating from a start and duration
    • Getting the duration
    • Checking if an instant is contained
    • Detecting overlap
  • DayOfWeek
    • Deriving from an Instant
    • Checking weekday or weekend
    • Calculating forward distance
  • TimeOfDay
    • Creating from components
    • Creating from a string
    • Deriving from an Instant
    • Named constructors
    • Comparing times
    • Measuring distance between times
    • Converting to other representations
  • LocalDate
    • Creating from components
    • Creating from a string
    • Today in a timezone
    • Projecting an Instant
    • Comparing dates
    • Day arithmetic
  • Timezone
    • Creating from an identifier
    • Creating a UTC timezone
    • Converting to DateTimeZone
  • Timezones
    • Creating from objects
    • Creating from strings
    • Getting all timezones
    • Finding a timezone by identifier
    • Finding a timezone by identifier with UTC fallback
    • Checking if a timezone exists in the collection
    • Getting all identifiers as strings
• License
• Contributing

Overview

Models time as immutable value objects for PHP, including instants, durations, periods, timezones, time-of-day, local dates, and day-of-week. All instants are normalized to UTC with microsecond precision, with strict parsing, formatting, and arithmetic operations. Declared as final readonly class for language-level immutability, with structural equality provided by the tiny-blocks value-object contract.

Installation

How to use

The library provides immutable value objects for representing points in time, quantities of time, and time intervals. All instants are normalized to UTC internally.

Instant

An Instant represents a single point on the timeline, always stored in UTC with microsecond precision.

Creating from the current moment

Captures the current moment with microsecond precision, normalized to UTC.

Creating from a string

Parses a date-time string with an explicit UTC offset. The value is normalized to UTC regardless of the original offset.

Creating from a database timestamp

Parses a database date-time string as UTC, with or without microsecond precision (e.g. MySQL DATETIME or DATETIME(6)).

Also supports timestamps without fractional seconds:

Creating from Unix seconds

Creates an Instant from a Unix timestamp in seconds.

Adding and subtracting time

Returns a new Instant shifted forward or backward by a Duration.

Measuring distance between instants

Returns the absolute Duration between two Instant objects.

The result is always non-negative regardless of direction:

Comparing instants

Provides strict temporal ordering between two Instant instances.

Emitting with sub-second precision

By default toIso8601() emits seconds only. Pass a Precision value to include fractional seconds in the output. Existing callers that omit the argument are unaffected.

Duration

A Duration represents an immutable, unsigned quantity of time measured in seconds. It has no reference point on the timeline. It expresses only "how much" time.

Creating durations

All factories reject negative values:

Arithmetic

Subtraction that would produce a negative result throws an exception:

Division

Returns the number of times one Duration fits wholly into another. The result is truncated toward zero:

Division by a zero Duration throws an exception:

Comparing durations

Converting to other units

Conversions truncate toward zero when the duration is not an exact multiple:

Period

A Period represents a half-open time interval [from, to) between two UTC instants. The start is inclusive and the end is exclusive.

Creating from two instants

The start must be strictly before the end:

Creating from a start and duration

Getting the duration

Checking if an instant is contained

The check is inclusive at the start and exclusive at the end:

Detecting overlap

Two half-open intervals [A, B) and [C, D) overlap when A < D and C < B:

Adjacent periods do not overlap:

DayOfWeek

A DayOfWeek represents a day of the week following ISO 8601, where Monday is 1 and Sunday is 7.

Deriving from an Instant

Checking weekday or weekend

Calculating forward distance

Returns the number of days forward from one day to another, always in the range [0, 6]. The distance is measured forward through the week:

TimeOfDay

A TimeOfDay represents a time of day (hour and minute) without date or timezone context. Values range from 00:00 to 23:59.

Creating from components

Creating from a string

Parses a string in HH:MM or HH:MM:SS format. When seconds are present, they are discarded:

Also accepts the HH:MM:SS format commonly returned by databases:

Deriving from an Instant

Extracts the time of day from an Instant in UTC:

Named constructors

Comparing times

Measuring distance between times

Returns the Duration between two times. The second time must be after the first:

Converting to other representations

LocalDate

A LocalDate is a value object representing a calendar date (year, month, day) without time and without timezone. Dates are always in the proleptic Gregorian calendar and restricted to the range 0001–9999.

Creating from components

Creating from a string

Accepts only the canonical ISO 8601 date format YYYY-MM-DD. Any other format raises InvalidLocalDate.

Today in a timezone

Projecting an Instant

Comparing dates

Day arithmetic

Timezone

A Timezone is a value object representing a single valid IANA timezone identifier.

Creating from an identifier

Creating a UTC timezone

Converting to DateTimeZone

Timezones

An immutable collection of Timezone objects.

Creating from objects

Creating from strings

Getting all timezones

Returns all Timezone objects in the collection:

Finding a timezone by identifier

Searches for a specific IANA identifier within the collection. Returns null if not found.

Finding a timezone by identifier with UTC fallback

Searches for a specific IANA identifier within the collection. Returns UTC if not found.

Checking if a timezone exists in the collection

Getting all identifiers as strings

Returns all timezone identifiers as plain strings:

License

Time is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.