DOCSEARCHbyAlgolia
Submit Docs

Brick\DateTime Documentation

repository·main·Indexed 18 days ago

https://github.com/brick/date-time

A PHP library providing immutable classes for working with dates and times following the ISO 8601 standard and inspired by Java's JSR 310. It includes core classes such as Instant, LocalDate, ZonedDateTime, and Period, as well as a Clock system (SystemClock, FixedClock, OffsetClock, ScaleClock) for time manipulation and testing. Requires PHP 8.2 or later.

Tokens
1.3K
Snippets
6
Records
10
Agent score
13%

What's inside Brick\DateTime

  1. Overview of Brick\DateTime core classes

    main

    The library provides a set of immutable classes in the Brick\DateTime namespace that follow the ISO 8601 standard. Key concepts include:

    • DayOfWeek: An enum representing days (e.g., Monday).
    • Duration: Time measured in seconds and nanoseconds.
    • Instant: A precise point in time (nanosecond precision).
    • Interval: A period between two Instant objects.
    • LocalDate: An isolated date (e.g., 2014-08-31).
    • LocalDateRange: An inclusive range of local dates.
    • LocalDateTime: A date-time without a time-zone.
    • LocalTime: An isolated time.
    • Month: An enum representing months.
    • MonthDay: A month and day combination without a year.
    • Period: A date-based amount of time (e.g., '2 years, 3 months').
    • TimeZoneOffset: An offset-based time-zone (e.g., +01:00).
    • TimeZoneRegion: A region-based time-zone (e.g., Europe/London).
    • Year: A year in the proleptic calendar.
    • YearMonth: A year and month combination.
    • ZonedDateTime: A date-time with a time-zone (conceptually equivalent to native PHP DateTime).

  2. How Clocks work in Brick\DateTime

    main

    All date-time objects read the current time from a Clock implementation. By default, the library uses the SystemClock.

    Available clock implementations in the Brick\DateTime\Clock namespace:

    • SystemClock: Returns the system time (default).
    • FixedClock: Returns a pre-configured time.
    • OffsetClock: Adds an offset to another clock.
    • ScaleClock: Scales the progression of another clock.

    In production, you typically use the default clock. In tests, you can pass a specific clock to now() methods or manipulate the DefaultClock globally.

    use Brick//DateTime//LocalDate;
use Brick//DateTime//TimeZone;

echo LocalDate::now(TimeZone::utc()); // 2017-10-04

  5. Manipulate the default clock for testing

    main

    To test application logic under specific time conditions, you can change the global DefaultClock.

    Warning: Always call DefaultClock::reset() after your tests (e.g., in a PHPUnit tearDown() method) to return to the system clock.

    Shortcut methods for testing:

    • freeze(): Freezes time to a specific point.
    • travelTo(Instant $instant): Moves time to a specific point, but allows time to continue moving forward from there.
    • travelBy(Duration $duration): Moves time forward or backward by a duration.
    • scale(float $factor): Makes time move at a given pace (e.g., 1 second becomes 60 seconds).
    use Brick//DateTime//Clock//DefaultClock;
use Brick//DateTime//Instant;

// Freeze time to a specific point
DefaultClock::freeze(Instant::of(2000000000));

$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20Z
echo $b, PHP_EOL; // 2033-05-18T03:33:20Z

DefaultClock::reset();

  6. Reference: Brick\DateTime Exceptions

    main

    The following exceptions are thrown by the library:

    • Brick\DateTime\DateTimeException: Thrown when an illegal operation is performed.
    • Brick\DateTime\Parser\DateTimeParseException: Thrown when parse() is called with an invalid string representation.

  7. DateTimeException::timeZoneOffsetSecondsMustBeMultipleOf60()

    main

    Creates a DateTimeException when a time zone offset in seconds is not a multiple of 60. Note that sub-minute offsets are only supported in PHP 8.1.7 and above.

    Parameters:

    • int $offsetSeconds: The time zone offset in seconds.
    DateTimeException::timeZoneOffsetSecondsMustBeMultipleOf60(45);

  8. DateTimeException::fieldNotInRange()

    main

    Creates a DateTimeException indicating that a specific field contains a value outside of the allowed minimum and maximum range.

    Parameters:

    • string $field: The name of the field being tested.
    • int $value: The actual value provided.
    • int $min: The minimum allowed value.
    • int $max: The maximum allowed value.
    DateTimeException::fieldNotInRange('month', 13, 1, 12);

  9. Handle Brick\DateTime errors with DateTimeException

    main
    All library-specific errors in Brick\DateTime extend the DateTimeException class. This exception is thrown when problems occur during the creation, querying, or manipulation of date-time objects. You can catch this exception to handle errors related to invalid field ranges, unsupported time zone offsets, or unknown time zone regions.