Code Monkey home page Code Monkey logo

php-temporal's Introduction

PHP-Temporal

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.

php-temporal's People

Contributors

ocram avatar

Stargazers

avatar Kim Lombard avatar Joe Leung avatar s90s avatar Adam LaCombe avatar Tyler Richards avatar Andrew-David J. avatar Victor avatar Travis van der F. avatar Nick avatar ignace nyamagana butera avatar Aitor García avatar Tomasz Sawicki avatar avatar

Watchers

James Cloos avatar avatar avatar

php-temporal's Issues

final class vs interface

Looking a the codebase I have to wonder why creating final classes that only contains constants instead of interfaces.

Something along these lines:

<?php

use Delight\Temporal\Iso8601\Iso8601Date;
use Delight\Temporal\Iso8601\Iso8601DateTime;
use Delight\Temporal\Iso8601\Iso8601Duration;
use Delight\Temporal\Iso8601\Iso8601Time;
use Delight\Temporal\Iso8601\Iso8601Weekday;
use Delight\Temporal\Timestamp\Unix;

/** Immutable representation of date and/or time */
final class Temporal implements 
    Iso8601Date,
    Iso8601DateTime,
    Iso8601DateDuration,
    Iso8601Time,
    Iso8601Weekday,
    Unix
{
... rest of the code here

Why:

  • These value will not change so their are valid candidate for being put in an interface
  • Someone could easily use your interface to implements them in their classes

How:

  • To avoid BC break you would need to name the interface(s) differently and then copy the current value in the current final class.

Open Issue

  • Should you have one big interface will all the constants of a serie of small interfaces ?

DateTime vs DateTimeImmutable

@ocram This is a question more than an Issue. Why do you use internally a DateTime object instead of a DateTimeImmutable object. The later would I believe remove any clone usage in your codebase, unless I'm missing something ?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.