Brick DateTime

https://github.com/brick/date-time
Admin
A powerful PHP library providing an extensive API of immutable classes for working with dates and...
Tokens:97,648
Snippets:664
Trust Score:9.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic usage example

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Shows creating an interval, getting its duration, checking containment, and computing intersection with another interval.

```php
use Brick\DateTime\Interval;
use Brick\DateTime\Instant;
use Brick\DateTime\Duration;

$interval = Interval::of(Instant::of(1_000_000_000), Instant::of(1_000_003_600));
echo $interval->getDuration();               // PT1H
echo $interval->contains($interval->getStart()); // true (start inclusive)
echo $interval->contains($interval->getEnd());   // false (end exclusive)

$other = Interval::of(Instant::of(1_000_000_001), Instant::of(1_000_000_002));
echo $interval->getIntersectionWith($other); // 2001-09-09T01:46:41Z/2001-09-09T01:46:42Z
```

--------------------------------

### Examples

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localdatetime.md

Basic usage and error handling examples for LocalDateTime.

```APIDOC
## Examples

### Basic use

```php
use Brick\DateTime\LocalDateTime;
use Brick\DateTime\Duration;
use Brick\DateTime\TimeZone;

$dt = LocalDateTime::of(2014, 8, 31, 10, 15, 30);
$dt = LocalDateTime::parse('2014-08-31T10:15:30');
echo $dt;                                        // 2014-08-31T10:15:30
echo $dt->plusHours(2);                          // 2014-08-31T12:15:30
echo $dt->plusDays(40);                          // 2014-10-10T10:15:30
echo $dt->withDate(LocalDate::parse('2001-01-01')); // 2001-01-01T10:15:30
$zoned = $dt->atTimeZone(TimeZone::utc());       // ZonedDateTime
```

### Error handling & immutable preservation

```php
use Brick\DateTime\DateTimeException;

$dt = LocalDateTime::of(2014, 2, 28);            // 2014-02-28T00:00
// modifiers never mutate the receiver:
$dt->plusYears(1);                               // 2015-02-28 (return value, $dt unchanged)
try {
    LocalDateTime::of(2014, 2, 29);
} catch (DateTimeException $e) {
    // "Invalid date February 29 as 2014 is not a leap year"
}
```
```

--------------------------------

### start(): void

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Starts the stopwatch by recording the current clock time as the start time. If already started, does nothing.

```APIDOC
## Method: `start(): void`

### Description
Starts the stopwatch. Records the current clock time as the start time. If the stopwatch is already running, this method does nothing.

### Parameters
None.

### Return
- `void` - No return value.

### Example
php
$stopwatch->start();

```

--------------------------------

### Examples

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/zoneddatetime.md

Basic usage and error handling examples for ZonedDateTime.

```APIDOC
## ZonedDateTime Usage Examples

### Description
Examples demonstrating basic usage, time zone conversions, arithmetic, and error handling.

### Basic Use

```php
use Brick\DateTime\ZonedDateTime;
use Brick\DateTime\LocalDateTime;
use Brick\DateTime\TimeZoneRegion;
use Brick\DateTime\Duration;

$paris = TimeZoneRegion::of('Europe/Paris');

$zdt = ZonedDateTime::of(LocalDateTime::of(2024, 3, 31, 2, 30), $paris);
// 2024-03-31T02:30 falls in the spring-forward gap; per of()'s documented
// strategy the result is shifted forward by the gap length using the later offset.

$sameInstant = $zdt->withTimeZoneSameInstant(TimeZoneRegion::of('America/New_York'));
$fixed = $zdt->withFixedOffsetTimeZone(); // same local date-time & offset, region dropped
echo $zdt->plusHours(24);                   // wall clock +24h (instant arithmetic)
echo $zdt->plusDays(1);                     // calendar arithmetic, re-resolved for DST
```

### Error Handling & Parsing

```php
use Brick\DateTime\DateTimeException;
use Brick\DateTime\Parser\DateTimeParseException;

try {
    ZonedDateTime::parse('2011-12-03T10:15:30+01:00[Europe/Paris]');
} catch (DateTimeParseException $e) {
    // malformed input
}

try {
    $zdt->getIntervalTo(ZonedDateTime::of(LocalDateTime::of(2020, 1, 1), $paris));
    // would throw if the argument instant is before $zdt
} catch (DateTimeException $e) {
    // "The end instant must not be before the start instant."
}
```
```

--------------------------------

### Install Easy Coding Standard

Source: https://github.com/brick/date-time/blob/main/README.md

Installs Easy Coding Standard in its own folder under tools/ecs.

```sh
composer install --working-dir=tools/ecs
```

--------------------------------

### Install PHPStan

Source: https://github.com/brick/date-time/blob/main/README.md

Installs PHPStan in its own folder under tools/phpstan.

```sh
composer install --working-dir=tools/phpstan
```

--------------------------------

### Install Rector

Source: https://github.com/brick/date-time/blob/main/README.md

Installs Rector in its own folder under tools/rector.

```sh
composer install --working-dir=tools/rector
```

--------------------------------

### Install brick/date-time via Composer

Source: https://github.com/brick/date-time/blob/main/_autodocs/README.md

Use this command to install the brick/date-time library. Requires PHP ^8.2.

```bash
composer require brick/date-time
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/brick/date-time/blob/main/README.md

Installs project dependencies before running checks.

```sh
composer install
```

--------------------------------

### Instant error handling

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Examples of handling DateTimeException when providing invalid nanosecond values or calculating intervals where the end is before the start.

```php
use Brick\DateTime\DateTimeException;

$instant = Instant::of(1000, 500_000_000);
try {
    $bad = $instant->withNano(1_000_000_000); // out of 0..999,999,999
} catch (DateTimeException $e) {
    // "Invalid nano-of-second: 1000000000 is not in the range 0 to 999999999."
}

try {
    $instant->getIntervalTo(Instant::of(900)); // end before start
} catch (DateTimeException $e) {
    // "The end instant must not be before the start instant."
}
```

--------------------------------

### Error handling example

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Demonstrates catching DateTimeException when creating an interval with end before start and when getting an intersection with non-overlapping intervals.

```php
use Brick\DateTime\DateTimeException;
use Brick\DateTime\Interval;
use Brick\DateTime\Instant;

try {
    Interval::of(Instant::of(100), Instant::of(99)); // end before start
} catch (DateTimeException $e) {
    // "The end instant must not be before the start instant."
}

try {
    $interval->getIntersectionWith(Interval::of(Instant::of(5_000_000_000), Instant::of(5_000_000_001)));
} catch (DateTimeException $e) {
    // 'Intervals "..." and "..." do not intersect.'
}
```

--------------------------------

### Basic usage of Stopwatch

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Demonstrates initializing a stopwatch, starting it, and retrieving the elapsed time.

```php
use Brick\DateTime\Stopwatch;

$stopwatch = new Stopwatch();
$stopwatch->start();
// ... work ...
$lap = $stopwatch->stop();        // Duration of this lap
echo $stopwatch->getElapsedTime();// accumulated total
```

--------------------------------

### Interval::getStart

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Returns the start instant of the interval (inclusive).

```APIDOC
## Interval::getStart

### Description
Returns the start instant of the interval. The start is inclusive.

### Method
`public function getStart(): Instant`

### Returns
- **Instant** - The start instant.

### Example
```php
$start = $interval->getStart();
```
```

--------------------------------

### Basic usage of LocalTime

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localtime.md

Shows how to create LocalTime instances using of, ofSecondOfDay, and midnight, and how to use plusHours, plusDuration, and withNano. The example demonstrates wrapping at midnight and formatting output.

```php
use Brick\DateTime\LocalTime;
use Brick\DateTime\Duration;

$time = LocalTime::of(10, 15, 30);
$time = LocalTime::ofSecondOfDay(37_230);       // 10:20:30
echo $time;                                      // 10:20:30
echo $time->plusHours(2);                        // 12:20:30 (wraps at midnight)
echo $time->plusDuration(Duration::ofSeconds(90)); // 10:22:00
echo $time->withNano(500_000_000);               // 10:20:30.5
echo LocalTime::midnight();                      // 00:00
```

--------------------------------

### LocalDateRange::getStart

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Returns the start date of the range.

```APIDOC
## LocalDateRange::getStart

### Description
Returns the start LocalDate of the range.

### Method
`public function getStart(): LocalDate`

### Returns
- **LocalDate** - The start date of the range.

### Example
```php
$start = $range->getStart();
```
```

--------------------------------

### Interval::withStart

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Returns a copy of this interval with a new start instant. Throws DateTimeException if the new start is after the end.

```APIDOC
## Interval::withStart

### Description
Returns a new Interval with the specified start instant, keeping the current end. Validates that the start is not after the end.

### Method
`public function withStart(Instant $start): Interval`

### Parameters
- **start** (Instant) - Required - The new start instant.

### Throws
- **DateTimeException** - If the new start is after the end.

### Returns
- **Interval** - A new Interval with the updated start.

### Example
```php
$newInterval = $interval->withStart(Instant::of(1_000_000_500));
```
```

--------------------------------

### YearMonthRange::getStart

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Returns the start year-month of the range.

```APIDOC
## YearMonthRange::getStart

### Description
Returns the start year-month of the range.

### Method
instance

### Signature
public function getStart(): YearMonth

### Returns
- **YearMonth** - The start year-month.
```

--------------------------------

### Basic Period usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/period.md

Examples of creating, normalizing, and calculating periods between dates.

```php
use Brick\DateTime\Period;
use Brick\DateTime\LocalDate;

$p = Period::of(2, 3, 4);                 // 2 years, 3 months, 4 days
$p = Period::ofYears(2)->plusMonths(3)->plusDays(4);
echo $p;                                   // P2Y3M4D
echo $p->normalized();                     // unchanged
echo Period::of(1, 15, 0)->normalized();   // P2Y3M
echo $p->multipliedBy(2);                  // P4Y6M8D
echo $p->negated();                        // P-2Y-3M-4D

$period = Period::between(LocalDate::of(2010, 1, 15), LocalDate::of(2011, 3, 18));
echo $period;                              // P1Y2M3D
```

--------------------------------

### getStartTime(): ?Instant

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Returns the time the stopwatch was started at, or null when not running.

```APIDOC
## Method: `getStartTime(): ?Instant`

### Description
Returns the start time of the stopwatch, or `null` if the stopwatch is not currently running.

### Parameters
None.

### Return
- `?Instant` - The start time as an `Instant`, or `null` if not running.

### Example
php
$startTime = $stopwatch->getStartTime();

```

--------------------------------

### LocalDateRange::withStart

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Returns a copy of this range with a new start date, re-validating the range.

```APIDOC
## LocalDateRange::withStart

### Description
Returns a new LocalDateRange with the specified start date, re-validating through of(). Throws DateTimeException if the new start is after the end. Returns $this if the start is unchanged.

### Method
`public function withStart(LocalDate $start): LocalDateRange`

### Parameters
- **$start** (LocalDate) - Required - The new start date.

### Returns
- **LocalDateRange** - A new range with the updated start, or $this if unchanged.

### Throws
- **DateTimeException** - If the new start is after the end date.

### Example
```php
$newRange = $range->withStart(LocalDate::of(2014, 2, 1));
```
```

--------------------------------

### Idempotent guards for Stopwatch

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Illustrates the idempotent behavior of start() and stop() methods.

```php
$stopwatch->start();
$stopwatch->start();        // no-op while running
$stopwatch->stop();         // returns the lap Duration
$stopwatch->stop();         // no-op, returns Duration::zero()
echo $stopwatch->isRunning(); // false
```

--------------------------------

### Constructor and factories

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Constructor is private; factories of(), from(), and parse() create instances. of() throws DateTimeException when end is before start. 'from()' applies month-only to start's year. parse() accepts ISO year-month-range format like '2001-02/2001-07' or '2001-02/07'.

```php
private function __construct(private YearMonth $start, private YearMonth $end)
public static function of(YearMonth $start, YearMonth $end): YearMonthRange
public static function from(DateTimeParseResult $result): YearMonthRange
public static function parse(string $text, ?DateTimeParser $parser = null): YearMonthRange
```

--------------------------------

### Constructor and factory method

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Private constructor and public static factory method for creating an Interval. The factory throws DateTimeException if the end is before the start.

```php
private function __construct(
    private Instant $start,
    private Instant $end,
) {
}

public static function of(Instant $startInclusive, Instant $endExclusive): Interval
```

--------------------------------

### Enum Usage Examples

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/enums.md

Common usage patterns for DayOfWeek and Month enums.

```php
use Brick\DateTime\DayOfWeek;
use Brick\DateTime\Month;

DayOfWeek::MONDAY->plus(3);          // DayOfWeek::THURSDAY
DayOfWeek::SUNDAY->isWeekend();      // true
DayOfWeek::all();                    // [MONDAY..SUNDAY]
DayOfWeek::all(DayOfWeek::WEDNESDAY);// [WEDNESDAY..TUESDAY]

Month::FEBRUARY->getLength(true);    // 29
Month::DECEMBER->plus(1);            // Month::JANUARY (wraps)

// native enum conversions
Month::from(8);                      // Month::AUGUST
```

--------------------------------

### Accessors and modifiers

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Methods to get the start and end instants, create modified intervals, and get the duration. withStart and withEnd validate through of() and throw DateTimeException on violation.

```php
public function getStart(): Instant
public function getEnd(): Instant
public function withStart(Instant $start): Interval
public function withEnd(Instant $end): Interval
public function getDuration(): Duration
```

--------------------------------

### Basic Instant usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Demonstrates creating an Instant, performing arithmetic operations, converting to a ZonedDateTime, and checking if an instant is in the future.

```php
use Brick\DateTime\Instant;
use Brick\DateTime\TimeZone;
use Brick\DateTime\Duration;

$instant = Instant::of(1_000_000_000);           // 2001-09-09T01:46:40Z
$later    = $instant->plus(Duration::ofHours(2));
$days     = $later->plusDays(90)->minusSeconds(5);
$tz       = $instant->atTimeZone(TimeZone::utc()); // ZonedDateTime
echo $instant->toISOString();

$future = Instant::now()->isFuture(); // uses the default (system) clock
```

--------------------------------

### Basic LocalDateTime usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localdatetime.md

Demonstrates creating, parsing, modifying, and converting a LocalDateTime instance.

```php
use Brick\DateTime\LocalDateTime;
use Brick\DateTime\Duration;
use Brick\DateTime\TimeZone;

$dt = LocalDateTime::of(2014, 8, 31, 10, 15, 30);
$dt = LocalDateTime::parse('2014-08-31T10:15:30');
echo $dt;                                        // 2014-08-31T10:15:30
echo $dt->plusHours(2);                          // 2014-08-31T12:15:30
echo $dt->plusDays(40);                          // 2014-10-10T10:15:30
echo $dt->withDate(LocalDate::parse('2001-01-01')); // 2001-01-01T10:15:30
$zoned = $dt->atTimeZone(TimeZone::utc());       // ZonedDateTime
```

--------------------------------

### Creating and using LocalDateRange and YearMonthRange

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Shows how to create LocalDateRange and YearMonthRange instances, count their elements, iterate over a range, and parse a range from a string.

```php
use Brick\DateTime\LocalDateRange;
use Brick\DateTime\YearMonthRange;
use Brick\DateTime\LocalDate;
use Brick\DateTime\YearMonth;

$aug = LocalDateRange::of(LocalDate::of(2014, 8, 1), LocalDate::of(2014, 8, 31));
echo $aug->count();                 // 31
foreach ($aug as $d) { /* each day of August */ }
echo LocalDateRange::parse('2001-02-03/04'); // 2001-02-03/2001-02-04

$range = YearMonthRange::of(YearMonth::of(2024, 1), YearMonth::of(2024, 3));
echo $range->count();               // 3
```

--------------------------------

### YearMonthRange::of

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Creates a YearMonthRange from a start and end YearMonth, both inclusive. Throws DateTimeException if the end is before the start.

```APIDOC
## YearMonthRange::of

### Description
Creates a YearMonthRange from a start and end YearMonth, both inclusive. Throws DateTimeException if the end is before the start.

### Method
static

### Signature
public static function of(YearMonth $start, YearMonth $end): YearMonthRange

### Parameters
- **start** (YearMonth) - Required - The start year-month (inclusive).
- **end** (YearMonth) - Required - The end year-month (inclusive).

### Throws
- **DateTimeException** - If the end year-month is before the start year-month.

### Returns
- **YearMonthRange** - The created range.
```

--------------------------------

### Instant factory methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Factory methods for creating Instant instances. of() normalizes the nano adjustment into the epoch second, epoch() returns a cached singleton for 1970-01-01T00:00:00Z, now() uses the given clock or DefaultClock::get(), min() returns (PHP_INT_MIN, 0), and max() returns (PHP_INT_MAX, 999_999_999).

```php
public static function of(int $epochSecond, int $nanoAdjustment = 0): Instant
public static function epoch(): Instant
public static function now(?Clock $clock = null): Instant
public static function min(): Instant
public static function max(): Instant
```

--------------------------------

### LocalDateRange::of

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Creates a LocalDateRange from a start and end LocalDate, both inclusive. Throws DateTimeException if the end is before the start.

```APIDOC
## LocalDateRange::of

### Description
Creates a new LocalDateRange with the given start and end dates, both inclusive. Throws DateTimeException if the end date is before the start date.

### Method
`public static function of(LocalDate $start, LocalDate $end): LocalDateRange`

### Parameters
- **$start** (LocalDate) - Required - The start date of the range (inclusive).
- **$end** (LocalDate) - Required - The end date of the range (inclusive).

### Throws
- **DateTimeException** - If the end date is before the start date.

### Example
```php
$range = LocalDateRange::of(LocalDate::of(2014, 1, 1), LocalDate::of(2014, 12, 31));
```
```

--------------------------------

### Interval::of

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Creates a new Interval from a start and end instant. Throws DateTimeException if the end is before the start.

```APIDOC
## Interval::of

### Description
Creates a new Interval with the given start and end instants. The start is inclusive, the end is exclusive.

### Method
`public static function of(Instant $startInclusive, Instant $endExclusive): Interval`

### Parameters
- **startInclusive** (Instant) - Required - The start instant (inclusive).
- **endExclusive** (Instant) - Required - The end instant (exclusive).

### Throws
- **DateTimeException** - If the end instant is before the start instant.

### Example
```php
$interval = Interval::of(Instant::of(1_000_000_000), Instant::of(1_000_003_600));
```
```

--------------------------------

### Deterministic testing with FixedClock

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Shows how to use a FixedClock to simulate time passage for testing purposes.

```php
use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\Instant;
use Brick\DateTime\Stopwatch;

$clock = new FixedClock(Instant::of(1_000));
$stopwatch = new Stopwatch($clock);

$stopwatch->start();
$clock->move(5);                  // 5 seconds pass
echo $stopwatch->getElapsedTime(); // PT5S
$lap = $stopwatch->stop();         // PT5S
echo $stopwatch->getElapsedTime(); // PT5S
```

--------------------------------

### Basic LocalDate usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localdate.md

Shows how to create LocalDate instances using Month enum or integer month, and demonstrates methods like plusMonths, withYear, plusPeriod, getDayOfWeek, and nextDayOfWeek. Note that plusMonths resolves the day down (e.g., 2014-08-31 plus 1 month gives 2014-09-30).

```php
use Brick\DateTime\LocalDate;
use Brick\DateTime\Month;
use Brick\DateTime\Period;

$date = LocalDate::of(2014, Month::AUGUST, 31);
$date = LocalDate::of(2014, 8, 31);            // int month also accepted
echo $date;                                    // 2014-08-31
echo $date->plusMonths(1);                     // 2014-09-30 (day resolved down)
echo $date->withYear(2015);                    // 2015-08-31
echo $date->plusPeriod(Period::ofYears(2));    // 2016-08-31
echo $date->getDayOfWeek();                    // Sunday
echo $date->nextDayOfWeek($date->getDayOfWeek()); // 2014-09-07
```

--------------------------------

### Year, MonthDay, YearWeek usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Shows common operations: checking leap year, getting last day of February, adjusting Feb 29 to a non-leap year, getting first day of a year-week, and parsing a week string.

```php
use Brick\DateTime\Year;
use Brick\DateTime\YearMonth;
use Brick\DateTime\MonthDay;
use Brick\DateTime\YearWeek;
use Brick\DateTime\DayOfWeek;

Year::of(2024)->isLeap();                    // true
Year::of(2024)->atMonth(Month::FEBRUARY)->getLastDay(); // 2024-02-29
MonthDay::of(2, 29)->atYear(2023);           // 2023-02-28 (adjusted)
YearWeek::of(2024, 1)->getFirstDay();        // 2024-01-01 (Monday)
YearWeek::parse('2024-W10')->atDay(DayOfWeek::WEDNESDAY); // 2024-03-06
```

--------------------------------

### YearMonth instance methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Lists the instance methods for querying, comparing, and manipulating YearMonth objects.

```php
public function getYear(): int
public function getMonth(): Month
public function getMonthValue(): int
public function isLeapYear(): bool
public function getLengthOfMonth(): int
public function getLengthOfYear(): int
public function compareTo(YearMonth $that): int
public function isEqualTo(YearMonth $that): bool
public function isBefore(YearMonth $that): bool
public function isBeforeOrEqualTo(YearMonth $that): bool
public function isAfter(YearMonth $that): bool
public function isAfterOrEqualTo(YearMonth $that): bool
public function withYear(int $year): YearMonth
public function withMonth(int|Month $month): YearMonth
public function getFirstDay(): LocalDate
public function getLastDay(): LocalDate
public function atDay(int $day): LocalDate
public function plusYears(int $years): YearMonth
public function plusMonths(int $months): YearMonth
public function minusYears(int $years): YearMonth
public function minusMonths(int $months): YearMonth
public function toLocalDateRange(): LocalDateRange
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### Comparison methods for Instant

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Methods for comparing instants. compareTo returns -1, 0, or 1. isFuture() and isPast() compare against Instant::now($clock) using the default system clock when no clock is provided.

```php
public function compareTo(Instant $that): int           // -1|0|1
public function isEqualTo(Instant $that): bool
public function isAfter(Instant $that): bool
public function isAfterOrEqualTo(Instant $that): bool
public function isBefore(Instant $that): bool
public function isBeforeOrEqualTo(Instant $that): bool
public function isBetweenInclusive(Instant $from, Instant $to): bool
public function isBetweenExclusive(Instant $from, Instant $to): bool
public function isFuture(?Clock $clock = null): bool
public function isPast(?Clock $clock = null): bool
```

--------------------------------

### Instant conversion methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Method signatures for converting an Instant to other types or formats.

```php
public function atTimeZone(TimeZone $timeZone): ZonedDateTime
public function getIntervalTo(Instant $that): Interval
public function toDecimal(): string
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### LocalDateRange::getIterator

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Returns a generator that yields each LocalDate from start to end inclusive.

```APIDOC
## LocalDateRange::getIterator

### Description
Returns a Generator that yields each LocalDate in the range from start to end, inclusive.

### Method
`public function getIterator(): Generator`

### Returns
- **Generator** - A generator yielding LocalDate objects.

### Example
```php
foreach ($range as $date) {
    echo $date;
}
```
```

--------------------------------

### DayOfWeek::all

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/enums.md

Returns an array of all days of the week, optionally starting from a specified day.

```APIDOC
## DayOfWeek::all

### Description
Returns an array of all seven days of the week, rotated so that the specified first day is the first element.

### Method
`public static function all(DayOfWeek $first = DayOfWeek::MONDAY): array`

### Parameters
- **first** (DayOfWeek) - Optional - The day to start the week; defaults to Monday.

### Returns
- **DayOfWeek[]** - An array of seven DayOfWeek cases, starting with the specified day.
```

--------------------------------

### LocalDateRange::toPeriod

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Converts this range to a Period object representing the inclusive days between start and end.

```APIDOC
## LocalDateRange::toPeriod

### Description
Converts this LocalDateRange to a Period object using Period::between($start, $end), representing the inclusive days.

### Method
`public function toPeriod(): Period`

### Returns
- **Period** - A Period representing the range.

### Example
```php
$period = $range->toPeriod();
```
```

--------------------------------

### Interval::contains

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Checks if the given instant is within the interval (start inclusive, end exclusive).

```APIDOC
## Interval::contains

### Description
Determines whether the specified instant is contained within this interval. The start is inclusive, the end is exclusive.

### Method
`public function contains(Instant $instant): bool`

### Parameters
- **instant** (Instant) - Required - The instant to check.

### Returns
- **bool** - `true` if the instant is within the interval, `false` otherwise.

### Example
```php
$contains = $interval->contains(Instant::of(1_000_001_000)); // true
```
```

--------------------------------

### Comparison Methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Methods to compare Instant instances, check equality, ordering, and whether an Instant is in the future or past relative to a clock.

```APIDOC
## Instant Comparison Methods

### Description
These methods allow comparing Instant instances, checking equality, ordering, and determining if an Instant is in the future or past relative to a given clock (default system clock).

### Methods
- `public function compareTo(Instant $that): int` // returns -1, 0, or 1
- `public function isEqualTo(Instant $that): bool`
- `public function isAfter(Instant $that): bool`
- `public function isAfterOrEqualTo(Instant $that): bool`
- `public function isBefore(Instant $that): bool`
- `public function isBeforeOrEqualTo(Instant $that): bool`
- `public function isBetweenInclusive(Instant $from, Instant $to): bool`
- `public function isBetweenExclusive(Instant $from, Instant $to): bool`
- `public function isFuture(?Clock $clock = null): bool`
- `public function isPast(?Clock $clock = null): bool`

### Behavior
- `isFuture()` and `isPast()` compare against `Instant::now($clock)` (default system clock).

### Source
`src/Instant.php:219`–`:307`.
```

--------------------------------

### Factory method signatures for ZonedDateTime

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/zoneddatetime.md

Lists the public static factory methods: of(), ofInstant(), now(), from(), parse(), and fromNativeDateTime(). The constructor is private; use these methods to create instances.

```php
public static function of(LocalDateTime $dateTime, TimeZone $timeZone): ZonedDateTime
public static function ofInstant(Instant $instant, TimeZone $timeZone): ZonedDateTime
public static function now(TimeZone $timeZone, ?Clock $clock = null): ZonedDateTime
public static function from(DateTimeParseResult $result): ZonedDateTime
public static function parse(string $text, ?DateTimeParser $parser = null): ZonedDateTime
public static function fromNativeDateTime(DateTimeInterface $dateTime): ZonedDateTime
```

--------------------------------

### YearMonthRange::toLocalDateRange

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Converts this range to a LocalDateRange, from the first day of the start month to the last day of the end month.

```APIDOC
## YearMonthRange::toLocalDateRange

### Description
Converts this range to a LocalDateRange, from the first day of the start month to the last day of the end month.

### Method
instance

### Signature
public function toLocalDateRange(): LocalDateRange

### Returns
- **LocalDateRange** - The corresponding date range.
```

--------------------------------

### Interval::withEnd

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Returns a copy of this interval with a new end instant. Throws DateTimeException if the new end is before the start.

```APIDOC
## Interval::withEnd

### Description
Returns a new Interval with the specified end instant, keeping the current start. Validates that the end is not before the start.

### Method
`public function withEnd(Instant $end): Interval`

### Parameters
- **end** (Instant) - Required - The new end instant.

### Throws
- **DateTimeException** - If the new end is before the start.

### Returns
- **Interval** - A new Interval with the updated end.

### Example
```php
$newInterval = $interval->withEnd(Instant::of(1_000_003_700));
```
```

--------------------------------

### Freeze and reset the global default clock with DefaultClock

Source: https://github.com/brick/date-time/blob/main/_autodocs/configuration.md

Shows how to freeze the global default clock at a fixed instant using DefaultClock::freeze(), check the frozen time with Instant::now(), and restore the system clock with DefaultClock::reset(). Always call reset() after tests to avoid leaking global state.

```php
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::freeze(Instant::of(2_000_000_000));
echo Instant::now();          // frozen at the given time
DefaultClock::reset();        // restore the system clock
```

--------------------------------

### Set operations

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Methods for checking containment, intersection, and getting the intersection. getIntersectionWith throws DateTimeException when intervals do not intersect.

```php
public function contains(Instant $instant): bool
public function intersectsWith(Interval $that): bool
public function getIntersectionWith(Interval $that): Interval
```

--------------------------------

### YearMonthRange::from

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Creates a YearMonthRange from a DateTimeParseResult. When the second part lacks a year field, only the month is applied to the start's year.

```APIDOC
## YearMonthRange::from

### Description
Creates a YearMonthRange from a DateTimeParseResult. When the second part lacks a year field, only the month is applied to the start's year.

### Method
static

### Signature
public static function from(DateTimeParseResult $result): YearMonthRange

### Parameters
- **result** (DateTimeParseResult) - Required - The parse result to create the range from.

### Returns
- **YearMonthRange** - The created range.
```

--------------------------------

### LocalTime factory method signatures

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localtime.md

Lists the static factory methods for creating LocalTime instances. These include of(), parse(), now(), and min()/max() among others. The constructor is private; use these methods instead.

```php
public static function of(int $hour, int $minute, int $second = 0, int $nano = 0): LocalTime
public static function ofSecondOfDay(int $secondOfDay, int $nanoOfSecond = 0): LocalTime
public static function from(DateTimeParseResult $result): LocalTime
public static function parse(string $text, ?DateTimeParser $parser = null): LocalTime
public static function fromNativeDateTime(DateTimeInterface $dateTime): LocalTime
public static function now(TimeZone $timeZone, ?Clock $clock = null): LocalTime
public static function midnight(): LocalTime
public static function noon(): LocalTime
public static function min(): LocalTime
public static function max(): LocalTime
public static function minOf(LocalTime ...$times): LocalTime
public static function maxOf(LocalTime ...$times): LocalTime
```

--------------------------------

### YearMonth factory methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Lists the factory methods for creating YearMonth instances: constructor, of, from, parse, and now.

```php
private function __construct(private int $year, private int $month)
public static function of(int $year, int|Month $month): YearMonth
public static function from(DateTimeParseResult $result): YearMonth
public static function parse(string $text, ?DateTimeParser $parser = null): YearMonth
public static function now(TimeZone $timeZone, ?Clock $clock = null): YearMonth
```

--------------------------------

### Serialization methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/interval.md

Methods for JSON serialization, ISO string conversion, and string representation. toISOString returns start + '/' + end.

```php
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### Comparison method signatures for LocalTime

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/localtime.md

Lists the public method signatures for comparing LocalTime instances: compareTo, isEqualTo, isBefore, isBeforeOrEqualTo, isAfter, and isAfterOrEqualTo. Each method takes another LocalTime as an argument and returns an int or bool.

```php
public function compareTo(LocalTime $that): int
public function isEqualTo(LocalTime $that): bool
public function isBefore(LocalTime $that): bool
public function isBeforeOrEqualTo(LocalTime $that): bool
public function isAfter(LocalTime $that): bool
public function isAfterOrEqualTo(LocalTime $that): bool
```

--------------------------------

### Use FixedClock with now() method

Source: https://github.com/brick/date-time/blob/main/README.md

Passes a FixedClock instance to LocalDate::now() to get a deterministic date. The output is 2001-09-09 for the given instant.

```php
use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\Instant;
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

$clock = new FixedClock(Instant::of(1000000000));
echo LocalDate::now(TimeZone::utc(), $clock); // 2001-09-09
```

--------------------------------

### Year instance methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Lists the instance methods available on Year objects, including getters, arithmetic, comparisons, and conversions.

```php
public function getValue(): int
public function isLeap(): bool
public function isValidMonthDay(MonthDay $monthDay): bool
public function getLength(): int
public function plus(int $years): Year
public function minus(int $years): Year
public function compareTo(Year $that): int
public function isEqualTo(Year $that): bool
public function isAfter(Year $that): bool
public function isBefore(Year $that): bool
public function atDay(int $dayOfYear): LocalDate
public function atMonth(int|Month $month): YearMonth
public function atMonthDay(MonthDay $monthDay): LocalDate
public function toLocalDateRange(): LocalDateRange
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### stop(): Duration

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Stops the stopwatch, adds the elapsed lap duration to the total, and clears the start time. If already stopped, returns Duration::zero().

```APIDOC
## Method: `stop(): Duration`

### Description
Stops the stopwatch. Adds the lap duration (from start time to current time) to the accumulated total and clears the start time. If the stopwatch is already stopped, does nothing and returns `Duration::zero()`.

### Parameters
None.

### Return
- `Duration` - The duration of the lap that was just stopped, or `Duration::zero()` if already stopped.

### Example
php
$lap = $stopwatch->stop();

```

--------------------------------

### MonthDay instance methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Instance methods for MonthDay. isValidYear() returns false only for Feb 29 in a non-leap year. withMonth() clamps the day to the new month's length. withDay() throws DateTimeException for days invalid in the month. atYear() combines with a year, turning Feb 29 into Feb 28 in non-leap years and throwing DateTimeException on invalid year. toISOString() returns --MM-DD.

```php
public function getMonth(): Month
public function getMonthValue(): int
public function getDayOfMonth(): int
public function compareTo(MonthDay $that): int
public function isEqualTo(MonthDay $that): bool
public function isBefore(MonthDay $that): bool
public function isAfter(MonthDay $that): bool
public function isValidYear(int $year): bool
public function withMonth(int|Month $month): MonthDay
public function withDay(int $day): MonthDay
public function atYear(int $year): LocalDate
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### new Stopwatch(?Clock $clock = null)

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/stopwatch.md

Creates a new Stopwatch instance. Optionally accepts a Clock to measure against; defaults to DefaultClock::get().

```APIDOC
## Constructor: `new Stopwatch(?Clock $clock = null)`

### Description
Creates a new Stopwatch instance. The clock is used to read the current time for measuring elapsed durations. If no clock is provided, the DefaultClock is used.

### Parameters
- **clock** (`?Clock`) - Optional - The clock to measure against. Defaults to `DefaultClock::get()`.

### Return
- `Stopwatch` - A new Stopwatch instance.

### Example
php
$stopwatch = new Stopwatch();

```

--------------------------------

### Year field validation example

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/fields.md

Demonstrates checking for leap years and validating year ranges using the Year field, which throws a DateTimeException for out-of-range values.

```php
use Brick\DateTime\Field\Year;
use Brick\DateTime\DateTimeException;

Year::isLeap(2024);           // true
try {
    Year::check(1_000_000);   // out of range
} catch (DateTimeException $e) {
    // "Invalid year: 1000000 is not in the range -999999 to 999999."
}
```

--------------------------------

### Handling DateTimeException for invalid ranges

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Demonstrates error handling when creating a range with an end date before the start date and when computing the intersection of non-intersecting ranges, both throwing DateTimeException.

```php
use Brick\DateTime\DateTimeException;
use Brick\DateTime\LocalDateRange;
use Brick\DateTime\LocalDate;

try {
    LocalDateRange::of(LocalDate::of(2024, 1, 1), LocalDate::of(2023, 12, 31));
} catch (DateTimeException $e) {
    // "The end date must not be before the start date."
}
try {
    $aug->getIntersectionWith(LocalDateRange::of(LocalDate::of(2015, 1, 1), LocalDate::of(2015, 1, 31)));
} catch (DateTimeException $e) {
    // 'Ranges "..." and "..." do not intersect.'
}
```

--------------------------------

### Basic Duration usage

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/duration.md

Demonstrates creating a duration, performing arithmetic operations, and converting to different time units.

```php
use Brick\DateTime\Duration;
use Brick\DateTime\Instant;

$d = Duration::ofHours(2)->plusMinutes(30)->plusSeconds(45);
echo $d;                                     // PT2H30M45S
echo $d->plus(Duration::ofMillis(1500));     // PT2H30M46.5S
echo $d->toMinutes();                        // 150
echo $d->toMinutesPart();                    // 30

$elapsed = Duration::between(Instant::of(0), Instant::of(90)); // PT90S
```

--------------------------------

### Get current date with default clock

Source: https://github.com/brick/date-time/blob/main/README.md

Shows the default behavior of LocalDate::now() using the system clock. The output is the current date in UTC, e.g., 2017-10-04.

```php
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

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

--------------------------------

### Year factory methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/year-month-day-week.md

Lists the factory methods for creating Year instances, including constructor, of, from, parse, and now.

```php
private function __construct(private int $year)
public static function of(int $year): Year
public static function from(DateTimeParseResult $result): Year
public static function parse(string $text, ?DateTimeParser $parser = null): Year
public static function now(TimeZone $timeZone, ?Clock $clock = null): Year
```

--------------------------------

### ZonedDateTime error handling and parsing

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/zoneddatetime.md

Error handling for parsing and interval calculation. Parsing malformed input throws DateTimeParseException; getIntervalTo throws DateTimeException if the argument instant is before the start instant.

```php
use Brick\DateTime\DateTimeException;
use Brick\DateTime\Parser\DateTimeParseException;

try {
    ZonedDateTime::parse('2011-12-03T10:15:30+01:00[Europe/Paris]');
} catch (DateTimeParseException $e) {
    // malformed input
}

try {
    $zdt->getIntervalTo(ZonedDateTime::of(LocalDateTime::of(2020, 1, 1), $paris));
    // would throw if the argument instant is before $zdt
} catch (DateTimeException $e) {
    // "The end instant must not be before the start instant."
}
```

--------------------------------

### Run PHPStan static analysis

Source: https://github.com/brick/date-time/blob/main/README.md

Runs PHPStan static analysis with the specified configuration file.

```sh
tools/phpstan/vendor/bin/phpstan --configuration=tools/phpstan/phpstan.neon
```

--------------------------------

### Instance methods

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/ranges.md

Methods of YearMonthRange: getStart, getEnd, isEqualTo, contains, getIterator, count, toLocalDateRange, jsonSerialize, toISOString, __toString.

```php
public function getStart(): YearMonth
public function getEnd(): YearMonth
public function isEqualTo(YearMonthRange $that): bool
public function contains(YearMonth $yearMonth): bool
public function getIterator(): Generator
public function count(): int
public function toLocalDateRange(): LocalDateRange
public function jsonSerialize(): string
public function toISOString(): string
public function __toString(): string
```

--------------------------------

### Accessor methods for Instant

Source: https://github.com/brick/date-time/blob/main/_autodocs/api-reference/instant.md

Returns the epoch second and the nano-of-second component of the instant.

```php
public function getEpochSecond(): int
public function getNano(): int
```
Tokens:
Raw