PHP code example of tiny-blocks / time

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

tiny-blocks / time example snippets

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::now();

$instant->toIso8601();            # 2026-02-17T10:30:00+00:00
$instant->toUnixSeconds();        # 1771324200
$instant->toDateTimeImmutable();  # DateTimeImmutable (UTC, with microseconds)

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17T13:30:00-03:00');

$instant->toIso8601();     # 2026-02-17T16:30:00+00:00
$instant->toUnixSeconds(); # 1771345800

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17T10:30:00Z');

$instant->toIso8601();     # 2026-02-17T10:30:00+00:00
$instant->toUnixSeconds(); # 1771324200

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17 08:27:21.106011');

$instant->toIso8601();                                    # 2026-02-17T08:27:21+00:00
$instant->toDateTimeImmutable()->format('Y-m-d H:i:s.u'); # 2026-02-17 08:27:21.106011

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17 08:27:21');

$instant->toIso8601(); # 2026-02-17T08:27:21+00:00

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromUnixSeconds(seconds: 0);

$instant->toIso8601();     # 1970-01-01T00:00:00+00:00
$instant->toUnixSeconds(); # 0

declare(strict_types=1);

use TinyBlocks\Time\Duration;
use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');

$instant->plus(duration: Duration::fromMinutes(minutes: 30))->toIso8601();  # 2026-02-17T10:30:00+00:00
$instant->plus(duration: Duration::fromHours(hours: 2))->toIso8601();       # 2026-02-17T12:00:00+00:00
$instant->minus(duration: Duration::fromSeconds(seconds: 60))->toIso8601(); # 2026-02-17T09:59:00+00:00

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-01-31T10:00:00+00:00');

$instant->plusMonths(months: 1)->toIso8601();   # 2026-02-28T10:00:00+00:00 (clamped)
$instant->plusYears(years: 1)->toIso8601();     # 2027-01-31T10:00:00+00:00
$instant->minusMonths(months: 1)->toIso8601();  # 2025-12-31T10:00:00+00:00
$instant->minusYears(years: 1)->toIso8601();    # 2025-01-31T10:00:00+00:00

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Timezone;

$newYork = Timezone::from(identifier: 'America/New_York');
$instant = Instant::fromString(value: '2026-02-08T07:30:00+00:00');

# The local time 2026-02-08 02:30 plus one month targets the non-existent local 2026-03-08 02:30,
# so PHP resolves it forward to 03:30 -04:00.
$instant->plusMonths(months: 1, zone: $newYork)->toIso8601(); # 2026-03-08T07:30:00+00:00

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$start = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
$end = Instant::fromString(value: '2026-02-17T11:30:00+00:00');

$duration = $start->durationUntil(other: $end);

$duration->toSeconds(); # 5400
$duration->toMinutes(); # 90
$duration->toHours();   # 1

$end->durationUntil(other: $start)->toSeconds(); # 5400

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$earlier = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
$later = Instant::fromString(value: '2026-02-17T10:30:00+00:00');

$earlier->isBefore(other: $later);         # true
$earlier->isAfter(other: $later);          # false
$earlier->isBeforeOrEqual(other: $later);  # true
$earlier->isAfterOrEqual(other: $later);   # false
$later->isAfter(other: $earlier);          # true
$later->isAfterOrEqual(other: $earlier);   # true

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Precision;

$instant = Instant::fromString(value: '2026-05-23T12:55:10.272097+00:00');

$instant->toIso8601();                                   # 2026-05-23T12:55:10+00:00
$instant->toIso8601(precision: Precision::Seconds);      # 2026-05-23T12:55:10+00:00
$instant->toIso8601(precision: Precision::Microseconds); # 2026-05-23T12:55:10.272097+00:00
$instant->toIso8601(precision: Precision::Milliseconds); # 2026-05-23T12:55:10.272+00:00

declare(strict_types=1);

use TinyBlocks\Mapper\Mapper;
use TinyBlocks\Time\Instant;

final readonly class Event
{
    public function __construct(public Instant $occurredAt, public string $name)
    {
    }
}

$mapper = Mapper::create();

$event = $mapper->toObject(type: Event::class, source: ['occurredAt' => '2026-02-17T10:30:00+00:00', 'name' => 'launch']);

$mapper->toArray(source: $event); # ['occurredAt' => '2026-02-17T10:30:00+00:00', 'name' => 'launch']

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$zero    = Duration::zero();
$seconds = Duration::fromSeconds(seconds: 90);
$minutes = Duration::fromMinutes(minutes: 30);
$hours   = Duration::fromHours(hours: 2);
$days    = Duration::fromDays(days: 7);

Duration::fromMinutes(minutes: -5); # throws InvalidSeconds

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$thirtyMinutes = Duration::fromMinutes(minutes: 30);
$fifteenMinutes = Duration::fromMinutes(minutes: 15);

$thirtyMinutes->plus(other: $fifteenMinutes)->toSeconds();  # 2700 (45 minutes)
$thirtyMinutes->minus(other: $fifteenMinutes)->toSeconds(); # 900 (15 minutes)

$fifteenMinutes->minus(other: $thirtyMinutes); # throws InvalidSeconds

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$total = Duration::fromMinutes(minutes: 90);
$slot = Duration::fromMinutes(minutes: 30);

$total->divide(other: $slot); # 3

$total->divide(other: Duration::zero()); # throws InvalidSeconds

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$short = Duration::fromMinutes(minutes: 15);
$long = Duration::fromHours(hours: 2);

$short->isLessThan(other: $long);    # true
$long->isGreaterThan(other: $short); # true
$short->isZero();                    # false
Duration::zero()->isZero();          # true

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$duration = Duration::fromSeconds(seconds: 5400);

$duration->toSeconds(); # 5400
$duration->toMinutes(); # 90
$duration->toHours();   # 1
$duration->toDays();    # 0

declare(strict_types=1);

use TinyBlocks\Time\SystemMonotonicClock;

$clock = new SystemMonotonicClock();

$clock->nanoseconds(); # 12345678901234 (an opaque counter, not a calendar value)

declare(strict_types=1);

use TinyBlocks\Time\SystemMonotonicClock;

$clock = new SystemMonotonicClock();

$start = $clock->nanoseconds();

# Perform the operation whose latency is being measured.
usleep(1000);

$elapsedNanos = $clock->nanoseconds() - $start;

declare(strict_types=1);

use TinyBlocks\Time\Stopwatch;
use TinyBlocks\Time\SystemMonotonicClock;

$stopwatch = Stopwatch::start(clock: new SystemMonotonicClock());

declare(strict_types=1);

use TinyBlocks\Time\Stopwatch;
use TinyBlocks\Time\SystemMonotonicClock;

$stopwatch = Stopwatch::start(clock: new SystemMonotonicClock());

# Perform the operation whose latency is being measured.
usleep(1500);

$stopwatch->elapsed()->toMilliseconds(); # 1.5

declare(strict_types=1);

use TinyBlocks\Time\Stopwatch;
use TinyBlocks\Time\SystemMonotonicClock;

$stopwatch = Stopwatch::start(clock: new SystemMonotonicClock());

usleep(1000);
$firstReading = $stopwatch->elapsed();

usleep(1000);
$secondReading = $stopwatch->elapsed();

$firstReading->toMilliseconds();  # approximately 1.0
$secondReading->toMilliseconds(); # approximately 2.0

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Period;

$period = Period::from(
    from: Instant::fromString(value: '2026-02-17T10:00:00+00:00'),
    to: Instant::fromString(value: '2026-02-17T11:00:00+00:00')
);

$period->from->toIso8601(); # 2026-02-17T10:00:00+00:00
$period->to->toIso8601();   # 2026-02-17T11:00:00+00:00

Period::from(from: $later, to: $earlier); # throws InvalidPeriod

declare(strict_types=1);

use TinyBlocks\Time\Duration;
use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Period;

$period = Period::startingAt(
    from: Instant::fromString(value: '2026-02-17T10:00:00+00:00'),
    duration: Duration::fromMinutes(minutes: 90)
);

$period->from->toIso8601(); # 2026-02-17T10:00:00+00:00
$period->to->toIso8601();   # 2026-02-17T11:30:00+00:00

$period->duration()->toSeconds(); # 5400
$period->duration()->toMinutes(); # 90

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$period->contains(instant: Instant::fromString(value: '2026-02-17T10:00:00+00:00')); # true (start, inclusive)
$period->contains(instant: Instant::fromString(value: '2026-02-17T10:30:00+00:00')); # true (middle)
$period->contains(instant: Instant::fromString(value: '2026-02-17T11:30:00+00:00')); # false (end, exclusive)

declare(strict_types=1);

use TinyBlocks\Time\Duration;
use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Period;

$periodA = Period::startingAt(
    from: Instant::fromString(value: '2026-02-17T10:00:00+00:00'),
    duration: Duration::fromHours(hours: 1)
);
$periodB = Period::startingAt(
    from: Instant::fromString(value: '2026-02-17T10:30:00+00:00'),
    duration: Duration::fromHours(hours: 1)
);

$periodA->overlapsWith(other: $periodB); # true
$periodB->overlapsWith(other: $periodA); # true

declare(strict_types=1);

use TinyBlocks\Time\Duration;
use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Period;

$first = Period::startingAt(
    from: Instant::fromString(value: '2026-02-17T10:00:00+00:00'),
    duration: Duration::fromHours(hours: 1)
);
$second = Period::startingAt(
    from: Instant::fromString(value: '2026-02-17T11:00:00+00:00'),
    duration: Duration::fromHours(hours: 1)
);

$first->overlapsWith(other: $second); # false

declare(strict_types=1);

use TinyBlocks\Time\DayOfWeek;
use TinyBlocks\Time\Instant;

$instant = Instant::fromString(value: '2026-02-17T10:30:00+00:00');
$day = DayOfWeek::fromInstant(instant: $instant);

$day;        # DayOfWeek::Tuesday
$day->value; # 2

declare(strict_types=1);

use TinyBlocks\Time\DayOfWeek;

DayOfWeek::Monday->isWeekday();   # true
DayOfWeek::Monday->isWeekend();   # false
DayOfWeek::Saturday->isWeekday(); # false
DayOfWeek::Saturday->isWeekend(); # true

declare(strict_types=1);

use TinyBlocks\Time\DayOfWeek;

DayOfWeek::Monday->distanceTo(other: DayOfWeek::Wednesday); # 2
DayOfWeek::Friday->distanceTo(other: DayOfWeek::Monday);    # 3 (forward through Sat, Sun, Mon)
DayOfWeek::Monday->distanceTo(other: DayOfWeek::Monday);    # 0

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$time = TimeOfDay::from(hour: 8, minute: 30);

$time->hour;   # 8
$time->minute; # 30

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$time = TimeOfDay::fromString(value: '14:30');

$time->hour;   # 14
$time->minute; # 30

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$time = TimeOfDay::fromString(value: '08:30:00');

$time->hour;       # 8
$time->minute;     # 30
$time->toString(); # 08:30

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\TimeOfDay;

$instant = Instant::fromString(value: '2026-02-17T14:30:00+00:00');
$time = TimeOfDay::fromInstant(instant: $instant);

$time->hour;   # 14
$time->minute; # 30

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$midnight = TimeOfDay::midnight(); # 00:00
$noon = TimeOfDay::noon();         # 12:00

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$morning = TimeOfDay::from(hour: 8, minute: 0);
$afternoon = TimeOfDay::from(hour: 14, minute: 30);

$morning->isBefore(other: $afternoon);        # true
$morning->isAfter(other: $afternoon);         # false
$morning->isBeforeOrEqual(other: $afternoon); # true
$afternoon->isAfterOrEqual(other: $morning);  # true

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$start = TimeOfDay::from(hour: 8, minute: 0);
$end = TimeOfDay::from(hour: 12, minute: 30);

$duration = $start->durationUntil(other: $end);

$duration->toMinutes(); # 270

declare(strict_types=1);

use TinyBlocks\Time\TimeOfDay;

$time = TimeOfDay::from(hour: 8, minute: 30);

$time->toMinutesSinceMidnight();  # 510
$time->toDuration()->toSeconds(); # 30600
$time->toString();                # 08:30

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$date = LocalDate::of(year: 2026, month: 5, day: 23);

$date->year();        # 2026
$date->month();       # 5
$date->dayOfMonth();  # 23
$date->toIso8601();   # 2026-05-23

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$date = LocalDate::fromString(value: '2026-05-23');

$date->toIso8601(); # 2026-05-23

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;
use TinyBlocks\Time\Timezone;

$today = LocalDate::today(zone: Timezone::from(identifier: 'America/Sao_Paulo'));

$today->toIso8601(); # 2026-05-23

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Timezone;

$instant = Instant::fromString(value: '2026-05-23T12:00:00+00:00');
$date = $instant->toLocalDate(zone: Timezone::utc());

$date->toIso8601(); # 2026-05-23

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;
use TinyBlocks\Time\TimeOfDay;
use TinyBlocks\Time\Timezone;

$date = LocalDate::of(year: 2026, month: 6, day: 15);
$instant = $date->atTime(
    time: TimeOfDay::from(hour: 0, minute: 0),
    zone: Timezone::from(identifier: 'America/Sao_Paulo')
);

$instant->toIso8601(); # 2026-06-15T03:00:00+00:00

$springForward = LocalDate::of(year: 2026, month: 3, day: 8);
$newYork = Timezone::from(identifier: 'America/New_York');

# 02:30 does not exist on this day, so it lands where 03:30 lands.
$springForward->atTime(time: TimeOfDay::from(hour: 2, minute: 30), zone: $newYork)->toIso8601();
# 2026-03-08T07:30:00+00:00

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$earlier = LocalDate::of(year: 2026, month: 1, day: 1);
$later = LocalDate::of(year: 2026, month: 12, day: 31);

$earlier->isBefore(other: $later);        # true
$earlier->isBeforeOrEqual(other: $later); # true
$later->isAfter(other: $earlier);         # true
$later->isAfterOrEqual(other: $earlier);  # true

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$date = LocalDate::of(year: 2026, month: 5, day: 23);

$date->plusDays(days: 10)->toIso8601();  # 2026-06-02
$date->minusDays(days: 30)->toIso8601(); # 2026-04-23

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$date = LocalDate::of(year: 2026, month: 1, day: 31);

$date->plusMonths(months: 1)->toIso8601();  # 2026-02-28 (clamped, February has 28 days)
$date->plusYears(years: 2)->toIso8601();    # 2028-01-31
$date->minusMonths(months: 2)->toIso8601(); # 2025-11-30 (clamped, November has 30 days)
$date->minusYears(years: 1)->toIso8601();   # 2025-01-31

$date->plusMonths(months: 1)->minusMonths(months: 1)->toIso8601(); # 2026-01-28

declare(strict_types=1);

use TinyBlocks\Mapper\Mapper;
use TinyBlocks\Time\LocalDate;

final readonly class Holiday
{
    public function __construct(public LocalDate $date, public string $name)
    {
    }
}

$mapper = Mapper::create();

$holiday = $mapper->toObject(type: Holiday::class, source: ['date' => '2026-05-23', 'name' => 'Labor Day']);

$mapper->toArray(source: $holiday); # ['date' => '2026-05-23', 'name' => 'Labor Day']

declare(strict_types=1);

use TinyBlocks\Time\Timezone;

$timezone = Timezone::from(identifier: 'America/Sao_Paulo');

$timezone->value;      # America/Sao_Paulo
$timezone->toString(); # America/Sao_Paulo

declare(strict_types=1);

use TinyBlocks\Time\Timezone;

$timezone = Timezone::utc();

$timezone->value; # UTC

declare(strict_types=1);

use TinyBlocks\Time\Timezone;

$timezone = Timezone::from(identifier: 'Asia/Tokyo');
$dateTimeZone = $timezone->toDateTimeZone();

$dateTimeZone->getName(); # Asia/Tokyo

declare(strict_types=1);

use TinyBlocks\Time\Timezone;
use TinyBlocks\Time\Timezones;

$timezones = Timezones::from(
    Timezone::from(identifier: 'America/Sao_Paulo'),
    Timezone::from(identifier: 'America/New_York'),
    Timezone::from(identifier: 'Asia/Tokyo')
);

$timezones->count(); # 3

declare(strict_types=1);

use TinyBlocks\Time\Timezones;

$timezones = Timezones::fromStrings('UTC', 'America/Sao_Paulo', 'Europe/London');

$timezones->count();     # 3
$timezones->toStrings(); # ["UTC", "America/Sao_Paulo", "Europe/London"]

$timezones->all(); # [Timezone("UTC"), Timezone("America/Sao_Paulo"), Timezone("Europe/London")]

declare(strict_types=1);

use TinyBlocks\Time\Timezones;

$timezones = Timezones::fromStrings('UTC', 'America/Sao_Paulo', 'Asia/Tokyo');

$timezones->findByIdentifier(iana: 'Asia/Tokyo');    # Timezone("Asia/Tokyo")
$timezones->findByIdentifier(iana: 'Europe/London'); # null

declare(strict_types=1);

use TinyBlocks\Time\Timezones;

$timezones = Timezones::fromStrings('UTC', 'America/Sao_Paulo', 'Asia/Tokyo');

$timezones->findByIdentifierOrUtc(iana: 'Asia/Tokyo');    # Timezone("Asia/Tokyo")
$timezones->findByIdentifierOrUtc(iana: 'Europe/London'); # Timezone("UTC")

declare(strict_types=1);

use TinyBlocks\Time\Timezones;

$timezones = Timezones::fromStrings('America/Sao_Paulo', 'Asia/Tokyo');

$timezones->contains(iana: 'Asia/Tokyo');       # true
$timezones->contains(iana: 'America/New_York'); # false

declare(strict_types=1);

use TinyBlocks\Time\Timezones;

$timezones = Timezones::fromStrings('UTC', 'America/Sao_Paulo', 'Europe/London');

$timezones->toStrings(); # ["UTC", "America/Sao_Paulo", "Europe/London"]

declare(strict_types=1);

use TinyBlocks\Time\Instant;

$morning = Instant::fromString(value: '2026-02-17T08:27:21+00:00');
$sameMoment = Instant::fromString(value: '2026-02-17T05:27:21-03:00');

$morning->equals(other: $sameMoment);             # true, both normalize to the same UTC moment
$morning->hashCode() === $sameMoment->hashCode(); # true

declare(strict_types=1);

use TinyBlocks\Time\LocalDate;

$parsed = LocalDate::fromString(value: '2026-02-17');
$composed = LocalDate::of(year: 2026, month: 2, day: 17);

$parsed->equals(other: $composed);             # true
$parsed->hashCode() === $composed->hashCode(); # true

declare(strict_types=1);

use TinyBlocks\Time\Instant;
use TinyBlocks\Time\Period;

$to = Instant::fromString(value: '2026-02-17T09:00:00+00:00');
$from = Instant::fromString(value: '2026-02-17T08:00:00+00:00');
$sameFrom = Instant::fromString(value: '2026-02-17T05:00:00-03:00');

$period = Period::from(from: $from, to: $to);
$samePeriod = Period::from(from: $sameFrom, to: $to);

$period->equals(other: $samePeriod); # true, the comparison walks into each Instant