delight-im/temporal

Immutable date and time for PHP with a convenient interface

Maintainers

Details

github.com/delight-im/PHP-Temporal

Homepage

Source

Issues

Installs: 147

Dependents: 0

Suggesters: 0

Security: 0

Stars: 13

Watchers: 3

Forks: 0

Open Issues: 2

v1.2.0 2018-04-16 22:25 UTC

Requires

  • php: >=5.6.0

MIT 87e610ba58293f22a09f02661b53fbc4d1eafe64

timedateparseparsingformatformattingdatetimemanipulatemanipulationimmutabledate-time

This package is auto-updated.

Last update: 2024-11-24 07:31:14 UTC

README

Immutable date and time for PHP with a convenient interface

Requirements

  • PHP 5.6.0+

Installation

  1. Include the library via Composer [?]:

    $ composer require delight-im/temporal

  2. Include the Composer autoloader:

    require __DIR__ . '/vendor/autoload.php';

  3. Make sure to set your default time zone in PHP, e.g.:

    \date_default_timezone_set('America/Los_Angeles');

Usage

Creating instances and parsing dates and time

$dateTime = \Delight\Temporal\Temporal::now();
// or
$dateTime = \Delight\Temporal\Temporal::now('Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromUnixSeconds(-14182916);
// or
$dateTime = \Delight\Temporal\Temporal::fromUnixSeconds(-14182916, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromUnixMillis(-14182916000);
// or
$dateTime = \Delight\Temporal\Temporal::fromUnixMillis(-14182916000, 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeExtended('1969-07-20T20:18:04+00:00');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeExtended('1969-07-20T20:18:04Z', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeBasic('19690720T201804Z');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateTimeBasic('19690720T201804+0000', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601DateExtended('1969-07-20');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateExtended('1969-07-20', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateBasic('19690720');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601DateBasic('19690720', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeExtended('20:18:04Z');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeExtended('20:18:04+00:00', 'America/Los_Angeles');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeBasic('201804+0000');
// or
$dateTime = \Delight\Temporal\Temporal::fromIso8601TimeBasic('201804Z', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromDateTime(1969, 7, 20, 20, 18, 4);
// or
$dateTime = \Delight\Temporal\Temporal::fromDateTime(1969, 7, 20, 20, 18, 4, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromDate(1969, 7, 20);
// or
$dateTime = \Delight\Temporal\Temporal::fromDate(1969, 7, 20, 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromTime(20, 18, 4);
// or
$dateTime = \Delight\Temporal\Temporal::fromTime(20, 18, 4, 'America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::fromFormat('20.07.1969', 'd.m.Y');
// or
$dateTime = \Delight\Temporal\Temporal::fromFormat('20.07.1969', 'd.m.Y', 'Asia/Tokyo');

// or

$dateTime = \Delight\Temporal\Temporal::fromDateTimeInterface(new \DateTime());
// or
$dateTime = \Delight\Temporal\Temporal::fromDateTimeInterface(new \DateTimeImmutable());

// or

$dateTime = \Delight\Temporal\Temporal::yesterday();
// or
$dateTime = \Delight\Temporal\Temporal::yesterday('America/Los_Angeles');

// or

$dateTime = \Delight\Temporal\Temporal::tomorrow();
// or
$dateTime = \Delight\Temporal\Temporal::tomorrow('America/Los_Angeles');

Adding and subtracting date and time

$dateTime = $dateTime->plusYears(7);
// or
$dateTime = $dateTime->minusYears(4);

// or

$dateTime = $dateTime->plusMonths(30);
// or
$dateTime = $dateTime->minusMonths(8);

// or

$dateTime = $dateTime->plusWeeks(6);
// or
$dateTime = $dateTime->minusWeeks(2);

// or

$dateTime = $dateTime->plusDays(28);
// or
$dateTime = $dateTime->minusDays(100);

// or

$dateTime = $dateTime->plusHours(36);
// or
$dateTime = $dateTime->minusHours(19);

// or

$dateTime = $dateTime->plusMinutes(90);
// or
$dateTime = $dateTime->minusMinutes(47);

// or

$dateTime = $dateTime->plusSeconds(30);
// or
$dateTime = $dateTime->minusSeconds(125);

// or

$dateTime = $dateTime->plusDuration('P3Y6M4DT12H30M5S');
// or
$dateTime = $dateTime->minusDuration('P3Y6M4DT12H30M5S');

// or

$dateTime = $dateTime->plusMonths(6)->plusWeeks(2)->minusDays(3);

Fetching individual components or units of date and time

$dateTime->getYear();
// or
$dateTime->getMonth();
// or
$dateTime->getDay();
// or
$dateTime->getHour();
// or
$dateTime->getMinute();
// or
$dateTime->getSecond();

// or

$dateTime->getWeekday();

// or

$dateTime->isMonday();
// or
$dateTime->isTuesday();
// or
$dateTime->isWednesday();
// or
$dateTime->isThursday();
// or
$dateTime->isFriday();
// or
$dateTime->isSaturday();
// or
$dateTime->isSunday();

// or

$dateTime->getWeekOfYear();
// or
$dateTime->getWeekYear();
// or
$dateTime->getDayOfYear();

Modifying individual components or units of date and time

$dateTime = $dateTime->withYear(1969);
// or
$dateTime = $dateTime->withMonth(7);
// or
$dateTime = $dateTime->withDay(20);
// or
$dateTime = $dateTime->withHour(20);
// or
$dateTime = $dateTime->withMinute(18);
// or
$dateTime = $dateTime->withSecond(4);

// or

$dateTime = $dateTime->withDate(1969, 7, 20);
// or
$dateTime = $dateTime->withTime(20, 18, 4);

// or

$dateTime = $dateTime->withDate(1969, 7, 20)->withMinute(0)->withSecond(0);

Skipping to boundaries of date and time units

$dateTime = $dateTime->startOfMinute();
// or
$dateTime = $dateTime->endOfMinute();

// or

$dateTime = $dateTime->startOfHour();
// or
$dateTime = $dateTime->endOfHour();

// or

$dateTime = $dateTime->startOfDay();
// or
$dateTime = $dateTime->endOfDay();

// or

$dateTime = $dateTime->startOfWeek();
// or
$dateTime = $dateTime->endOfWeek();

// or

$dateTime = $dateTime->startOfMonth();
// or
$dateTime = $dateTime->endOfMonth();

// or

$dateTime = $dateTime->startOfYear();
// or
$dateTime = $dateTime->endOfYear();

// or

$dateTime = $dateTime->startOfDecade();
// or
$dateTime = $dateTime->endOfDecade();

// or

$dateTime = $dateTime->startOfCentury();
// or
$dateTime = $dateTime->endOfCentury();

// or

$dateTime = $dateTime->startOfMillennium();
// or
$dateTime = $dateTime->endOfMillennium();

// or

$dateTime = $dateTime->startOfMonth()->endOfWeek()->startOfDay();

Formatting and outputting date and time

$dateTime->toIso8601DateTimeExtended();
// or
$dateTime->toIso8601DateTimeBasic();

// or

$dateTime->toIso8601DateExtended();
// or
$dateTime->toIso8601DateBasic();

// or

$dateTime->toIso8601TimeExtended();
// or
$dateTime->toIso8601TimeBasic();

// or

$dateTime->toUnixSeconds();
// or
$dateTime->toUnixMillis();

// or

$dateTime->toFormat('d.m.Y');
// or
$dateTime->toFormat('l jS \of F Y h:i:s A');

// or

$dateTime->toDateTime();
// or
$dateTime->toDateTimeImmutable();

Fetching decades, centuries and millennia from dates

$dateTime->getDecadeOrdinal();
// or
$dateTime->getDecadeNominal();
// or
$dateTime->getYearInDecade();

// or

$dateTime->getCenturyOrdinal();
// or
$dateTime->getCenturyNominal();
// or
$dateTime->getYearInCentury();

// or

$dateTime->getMillenniumOrdinal();
// or
$dateTime->getMillenniumNominal();
// or
$dateTime->getYearInMillennium();

Checking for daylight saving time (DST)

$dateTime->isDst();

Checking for leap years

$dateTime->isLeapYear();

Checking for special dates

$dateTime->isToday();
// or
$dateTime->isYesterday();
// or
$dateTime->isTomorrow();

// or

$dateTime->isAnniversary();

// or

$dateTime->isThisWeek();
// or
$dateTime->isLastWeek();
// or
$dateTime->isNextWeek();

// or

$dateTime->isThisMonth();
// or
$dateTime->isLastMonth();
// or
$dateTime->isNextMonth();

// or

$dateTime->isThisYear();
// or
$dateTime->isLastYear();
// or
$dateTime->isNextYear();

// or

$dateTime->isThisDecade();
// or
$dateTime->isLastDecade();
// or
$dateTime->isNextDecade();

// or

$dateTime->isThisCentury();
// or
$dateTime->isLastCentury();
// or
$dateTime->isNextCentury();

// or

$dateTime->isThisMillennium();
// or
$dateTime->isLastMillennium();
// or
$dateTime->isNextMillennium();

Calculating differences between two instances of date and time

$dateTime->calculateMillisUntil($otherDateTime);
// or
$dateTime->calculateSecondsUntil($otherDateTime);
// or
$dateTime->calculateMinutesUntil($otherDateTime);

// or

\Delight\Temporal\Duration $duration = $dateTime->calculateDurationUntil($otherDateTime);

Reading and writing durations of date and time

$duration->getYears();
// or
$duration->getMonths();
// or
$duration->getWeeks();
// or
$duration->getDays();

// or

$duration->getHours();
// or
$duration->getMinutes();
// or
$duration->getSeconds();

// or

$duration->isPositive();
// or
$duration->isNegative();
// or
$duration->getSign();

// or

$duration->toIso8601();

// or

$duration->toAverageYears();
// or
$duration->toAverageMonths();
// or
$duration->toAverageWeeks();
// or
$duration->toAverageDays();
// or
$duration->toAverageHours();
// or
$duration->toAverageMinutes();
// or
$duration->toAverageSeconds();

// or

$duration = \Delight\Temporal\Duration::fromDateTime(2, 7, 15, 20, 45, 0);
// or
$duration = \Delight\Temporal\Duration::fromDateTime(4, 0, 7);
// or
$duration = \Delight\Temporal\Duration::fromDateTime(3, 5, 26, 0, 0, 0, -1);

// or

$duration = \Delight\Temporal\Duration::fromWeeks(42);
// or
$duration = \Delight\Temporal\Duration::fromWeeks(8, -1);

// or

$duration = \Delight\Temporal\Duration::fromIso8601('P1M');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P1Y14D');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P1MT12H');
// or
$duration = \Delight\Temporal\Duration::fromIso8601('P3Y6M4DT12H30M5S');

// or

$duration = $duration->plus($otherDuration);
// or
$duration = $duration->multipliedBy(4);
// or
$duration = $duration->invert();

// or

$duration = $duration->plus($otherDuration->invert())->multipliedBy(2);

Comparing instances of date and time with each other

Equality

$dateTime->isSame($otherDateTime);
// or
$dateTime->isMinuteSame($otherDateTime);
// or
$dateTime->isHourSame($otherDateTime);
// or
$dateTime->isDaySame($otherDateTime);
// or
$dateTime->isMonthSame($otherDateTime);
// or
$dateTime->isYearSame($otherDateTime);
// or
$dateTime->isDecadeSame($otherDateTime);
// or
$dateTime->isCenturySame($otherDateTime);
// or
$dateTime->isMillenniumSame($otherDateTime);

Less than

$dateTime->isBefore($otherDateTime);
// or
$dateTime->isMinuteBefore($otherDateTime);
// or
$dateTime->isHourBefore($otherDateTime);
// or
$dateTime->isDayBefore($otherDateTime);
// or
$dateTime->isMonthBefore($otherDateTime);
// or
$dateTime->isYearBefore($otherDateTime);
// or
$dateTime->isDecadeBefore($otherDateTime);
// or
$dateTime->isCenturyBefore($otherDateTime);
// or
$dateTime->isMillenniumBefore($otherDateTime);

Greater than

$dateTime->isAfter($otherDateTime);
// or
$dateTime->isMinuteAfter($otherDateTime);
// or
$dateTime->isHourAfter($otherDateTime);
// or
$dateTime->isDayAfter($otherDateTime);
// or
$dateTime->isMonthAfter($otherDateTime);
// or
$dateTime->isYearAfter($otherDateTime);
// or
$dateTime->isDecadeAfter($otherDateTime);
// or
$dateTime->isCenturyAfter($otherDateTime);
// or
$dateTime->isMillenniumAfter($otherDateTime);

Less than or equal to

$dateTime->isBeforeOrSame($otherDateTime);
// or
$dateTime->isMinuteBeforeOrSame($otherDateTime);
// or
$dateTime->isHourBeforeOrSame($otherDateTime);
// or
$dateTime->isDayBeforeOrSame($otherDateTime);
// or
$dateTime->isMonthBeforeOrSame($otherDateTime);
// or
$dateTime->isYearBeforeOrSame($otherDateTime);
// or
$dateTime->isDecadeBeforeOrSame($otherDateTime);
// or
$dateTime->isCenturyBeforeOrSame($otherDateTime);
// or
$dateTime->isMillenniumBeforeOrSame($otherDateTime);

Greater than or equal to

$dateTime->isAfterOrSame($otherDateTime);
// or
$dateTime->isMinuteAfterOrSame($otherDateTime);
// or
$dateTime->isHourAfterOrSame($otherDateTime);
// or
$dateTime->isDayAfterOrSame($otherDateTime);
// or
$dateTime->isMonthAfterOrSame($otherDateTime);
// or
$dateTime->isYearAfterOrSame($otherDateTime);
// or
$dateTime->isDecadeAfterOrSame($otherDateTime);
// or
$dateTime->isCenturyAfterOrSame($otherDateTime);
// or
$dateTime->isMillenniumAfterOrSame($otherDateTime);

Checking whether dates and times are in the past or future

$dateTime->isPast();
// or
$dateTime->isPastMinute();
// or
$dateTime->isPastHour();
// or
$dateTime->isPastDay();
// or
$dateTime->isPastMonth();
// or
$dateTime->isPastYear();
// or
$dateTime->isPastDecade();
// or
$dateTime->isPastCentury();
// or
$dateTime->isPastMillennium();

// or

$dateTime->isFuture();
// or
$dateTime->isFutureMinute();
// or
$dateTime->isFutureHour();
// or
$dateTime->isFutureDay();
// or
$dateTime->isFutureMonth();
// or
$dateTime->isFutureYear();
// or
$dateTime->isFutureDecade();
// or
$dateTime->isFutureCentury();
// or
$dateTime->isFutureMillennium();

Changing and converting timezones

$dateTime = $dateTime->withTimeZone('UTC');
// or
$dateTime = $dateTime->withTimeZone('America/Los_Angeles');
// or
$dateTime = $dateTime->withTimeZone('Asia/Tokyo');

// or

$dateTime = $dateTime->withDefaultTimeZone();

Contributing

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.

License

This project is licensed under the terms of the MIT License.