PHPackages                             tiny-blocks/time - 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. [PSR & Standards](/categories/psr-standards)
4. /
5. tiny-blocks/time

ActiveLibrary[PSR & Standards](/categories/psr-standards)

tiny-blocks/time
================

Models time as immutable value objects for PHP: instants, durations, periods, timezones, and time-of-day, all UTC-normalized.

2.3.0(3w ago)13095MITPHPPHP ^8.5CI passing

Since Feb 17Pushed 1w agoCompare

[ Source](https://github.com/tiny-blocks/time)[ Packagist](https://packagist.org/packages/tiny-blocks/time)[ Docs](https://github.com/tiny-blocks/time)[ RSS](/packages/tiny-blocks-time/feed)WikiDiscussions main Synced yesterday

READMEChangelog (10)Dependencies (30)Versions (13)Used By (5)

Time
====

[](#time)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tiny-blocks/time/blob/main/LICENSE)

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [Instant](#instant)
        - [Creating from the current moment](#creating-from-the-current-moment)
        - [Creating from a string](#creating-from-a-string)
        - [Creating from a database timestamp](#creating-from-a-database-timestamp)
        - [Creating from Unix seconds](#creating-from-unix-seconds)
        - [Adding and subtracting time](#adding-and-subtracting-time)
        - [Measuring distance between instants](#measuring-distance-between-instants)
        - [Comparing instants](#comparing-instants)
        - [Emitting with sub-second precision](#emitting-with-sub-second-precision)
        - [Serializing with the mapper](#serializing-with-the-mapper)
    - [Duration](#duration)
        - [Creating durations](#creating-durations)
        - [Arithmetic](#arithmetic)
        - [Division](#division)
        - [Comparing durations](#comparing-durations)
        - [Converting to other units](#converting-to-other-units)
    - [MonotonicClock](#monotonicclock)
        - [Reading the current nanoseconds](#reading-the-current-nanoseconds)
        - [Measuring an elapsed window](#measuring-an-elapsed-window)
    - [Stopwatch](#stopwatch)
        - [Starting a stopwatch](#starting-a-stopwatch)
        - [Reading the elapsed interval](#reading-the-elapsed-interval)
        - [Reading the elapsed interval more than once](#reading-the-elapsed-interval-more-than-once)
    - [Period](#period)
        - [Creating from two instants](#creating-from-two-instants)
        - [Creating from a start and duration](#creating-from-a-start-and-duration)
        - [Getting the duration](#getting-the-duration)
        - [Checking if an instant is contained](#checking-if-an-instant-is-contained)
        - [Detecting overlap](#detecting-overlap)
    - [DayOfWeek](#dayofweek)
        - [Deriving from an Instant](#deriving-from-an-instant)
        - [Checking weekday or weekend](#checking-weekday-or-weekend)
        - [Calculating forward distance](#calculating-forward-distance)
    - [TimeOfDay](#timeofday)
        - [Creating from components](#creating-from-components)
        - [Creating from a string](#creating-from-a-string-1)
        - [Deriving from an Instant](#deriving-from-an-instant-1)
        - [Named constructors](#named-constructors)
        - [Comparing times](#comparing-times)
        - [Measuring distance between times](#measuring-distance-between-times)
        - [Converting to other representations](#converting-to-other-representations)
    - [LocalDate](#localdate)
        - [Creating from components](#creating-from-components-1)
        - [Creating from a string](#creating-from-a-string-2)
        - [Today in a timezone](#today-in-a-timezone)
        - [Projecting an Instant](#projecting-an-instant)
        - [Comparing dates](#comparing-dates)
        - [Day arithmetic](#day-arithmetic)
        - [Serializing with the mapper](#serializing-with-the-mapper-1)
    - [Timezone](#timezone)
        - [Creating from an identifier](#creating-from-an-identifier)
        - [Creating a UTC timezone](#creating-a-utc-timezone)
        - [Converting to DateTimeZone](#converting-to-datetimezone)
    - [Timezones](#timezones)
        - [Creating from objects](#creating-from-objects)
        - [Creating from strings](#creating-from-strings)
        - [Getting all timezones](#getting-all-timezones)
        - [Finding a timezone by identifier](#finding-a-timezone-by-identifier)
        - [Finding a timezone by identifier with UTC fallback](#finding-a-timezone-by-identifier-with-utc-fallback)
        - [Checking if a timezone exists in the collection](#checking-if-a-timezone-exists-in-the-collection)
        - [Getting all identifiers as strings](#getting-all-identifiers-as-strings)
- [License](#license)
- [Contributing](#contributing)

Overview
--------

[](#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
------------

[](#installation)

```
composer require tiny-blocks/time
```

How to use
----------

[](#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

[](#instant)

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

#### Creating from the current moment

[](#creating-from-the-current-moment)

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

```