Times and Dates

CodeIgniter provides a fully-localized, immutable, date/time class that is built on PHP’s DateTime object, but uses the Intl extension’s features to convert times across timezones and display the output correctly for different locales. This class is the Time class and lives in the CodeIgniter\I18n namespace.

Note

Since the Time class extends DateTime, if there are features that you need that this class doesn’t provide, you can likely find them within the DateTime class itself.

Instantiating 

There are several ways that a new Time instance can be created. The first is simply to create a new instance like any other class. When you do it this way, you can pass in a string representing the desired time. This can be any string that PHP’s strtotime function can parse:

<?php

use CodeIgniter\I18n\Time;

$myTime = new Time('+3 week');
$myTime = new Time('now');

You can pass in strings representing the timezone and the locale in the second and parameters, respectively. Timezones can be any supported by PHP’s DateTimeZone class. The locale can be any supported by PHP’s Locale class. If no locale or timezone is provided, the application defaults will be used.

<?php

$myTime = new Time('now', 'America/Chicago', 'en_US');

now()

The Time class has several helper methods to instantiate the class. The first of these is the now() method that returns a new instance set to the current time. You can pass in strings representing the timezone and the locale in the second and parameters, respectively. If no locale or timezone is provided, the application defaults will be used.

<?php

$myTime = Time::now('America/Chicago', 'en_US');

parse()

This helper method is a static version of the default constructor. It takes a string acceptable as DateTime’s constructor as the first parameter, a timezone as the second parameter, and the locale as the third parameter:

<?php

$myTime = Time::parse('next Tuesday', 'America/Chicago', 'en_US');

today()

Returns a new instance with the date set to the current date, and the time set to midnight. It accepts strings for the timezone and locale in the first and second parameters:

<?php

$myTime = Time::today('America/Chicago', 'en_US');

yesterday()

Returns a new instance with the date set to the yesterday’s date and the time set to midnight. It accepts strings for the timezone and locale in the first and second parameters:

<?php

$myTime = Time::yesterday('America/Chicago', 'en_US');

tomorrow()

Returns a new instance with the date set to tomorrow’s date and the time set to midnight. It accepts strings for the timezone and locale in the first and second parameters:

<?php

$myTime = Time::tomorrow('America/Chicago', 'en_US');

createFromDate()

Given separate inputs for year, month, and day, will return a new instance. If any of these parameters are not provided, it will use the current value to fill it in. Accepts strings for the timezone and locale in the fourth and fifth parameters:

<?php

$today       = Time::createFromDate();     // Uses current year, month, and day
$anniversary = Time::createFromDate(2018); // Uses current month and day
$date        = Time::createFromDate(2018, 3, 15, 'America/Chicago', 'en_US');

createFromTime()

Like createFromDate() except it is only concerned with the hours, minutes, and seconds. Uses the current day for the date portion of the Time instance. Accepts strings for the timezone and locale in the fourth and fifth parameters:

<?php

$lunch  = Time::createFromTime(11, 30);     // 11:30 am today
$dinner = Time::createFromTime(18, 00, 00); // 6:00 pm today
$time   = Time::createFromTime($hour, $minutes, $seconds, $timezone, $locale);

create()

A combination of the previous two methods, takes year, month, day, hour, minutes, and seconds as separate parameters. Any value not provided will use the current date and time to determine. Accepts strings for the timezone and locale in the fourth and fifth parameters:

<?php

$time = Time::create($year, $month, $day, $hour, $minutes, $seconds, $timezone, $locale);

createFromFormat()

This is a replacement for DateTime’s method of the same name. This allows the timezone to be set at the same time, and returns a Time instance, instead of DateTime:

<?php

$time = Time::createFromFormat('j-M-Y', '15-Feb-2009', 'America/Chicago');

createFromTimestamp()

This method takes a UNIX timestamp and, optionally, the timezone and locale, to create a new Time instance:

<?php

$time = Time::createFromTimestamp(1501821586, 'America/Chicago', 'en_US');

createFromInstance()

When working with other libraries that provide a DateTime instance, you can use this method to convert that to a Time instance, optionally setting the locale. The timezone will be automatically determined from the DateTime instance passed in:

<?php

$dt   = new DateTime('now');
$time = Time::createFromInstance($dt, 'en_US');

toDateTime()

While not an instantiator, this method is the opposite of the instance method, allowing you to convert a Time instance into a DateTime instance. This preserves the timezone setting, but loses the locale, since DateTime is not aware of locales:

<?php

$datetime = Time::toDateTime();

Displaying the Value 

Since the Time class extends DateTime, you get all of the output methods that provides, including the format() method. However, the DateTime methods do not provide a localized result. The Time class does provide a number of helper methods to display localized versions of the value, though.

toLocalizedString()

This is the localized version of DateTime’s format() method. Instead of using the values you might be familiar with, though, you must use values acceptable to the IntlDateFormatter class. A full listing of values can be found here.

<?php

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toLocalizedString('MMM d, yyyy'); // March 9, 2016

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toLocalizedString('MMM d, yyyy'); // مارس ۹, ۲۰۱۶

toDateTimeString()

This is the first of three helper methods to work with the IntlDateFormatter without having to remember their values. This will return a localized version of string formatted as (Y-m-d H:i:s):

<?php

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateTimeString(); // 2016-03-09 12:00:00

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateTimeString(); // ۲۰۱۶-۰۳-۰۹ ۱۲:۰۰:۰۰

toDateString()

Displays just the localized version of date portion of the Time:

<?php

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateString(); // 2016-03-09

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateString(); // ۲۰۱۶-۰۳-۰۹

toTimeString()

Displays just the localized version of time portion of the value:

<?php

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toTimeString(); // 12:00:00

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toTimeString(); // ۱۲:۰۰:۰۰

humanize()

This methods returns a string that displays the difference between the current date/time and the instance in a human readable format that is geared towards being easily understood. It can create strings like ‘3 hours ago’, ‘in 1 month’, etc:

<?php

// Assume current time is: March 10, 2017 (America/Chicago)
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

echo $time->humanize(); // 1 year ago

The exact time displayed is determined in the following manner:

Time difference	Result
$time > 1 year && < 2 years	in 1 year / 1 year ago
$time > 1 month && < 1 year	in 6 months / 6 months ago
$time > 7 days && < 1 month	in 3 weeks / 3 weeks ago
$time > today && < 7 days	in 4 days / 4 days ago
$time == tomorrow / yesterday	Tomorrow / Yesterday
$time > 59 minutes && < 1 day	in 2 hours / 2 hours ago
$time > now && < 1 hour	in 35 minutes / 35 minutes ago
$time == now	Now

The exact language used is controlled through the language file, Time.php.

Working with Individual Values 

The Time object provides a number of methods to allow to get and set individual items, like the year, month, hour, etc, of an existing instance. All of the values retrieved through the following methods will be fully localized and respect the locale that the Time instance was created with.

All of the following getX() and setX() methods can also be used as if they were a class property. So, any calls to methods like getYear() can also be accessed through $time->year, and so on.

Getters 

The following basic getters exist:

<?php

$time = Time::parse('August 12, 2016 4:15:23pm');

echo $time->getYear();   // 2016
echo $time->getMonth();  // 8
echo $time->getDay();    // 12
echo $time->getHour();   // 16
echo $time->getMinute(); // 15
echo $time->getSecond(); // 23

echo $time->year;   // 2016
echo $time->month;  // 8
echo $time->day;    // 12
echo $time->hour;   // 16
echo $time->minute; // 15
echo $time->second; // 23

In addition to these, a number of methods exist to provide additional information about the date:

<?php

$time = Time::parse('August 12, 2016 4:15:23pm');

echo $time->getDayOfWeek();   // 6 - but may vary based on locale's starting day of the week
echo $time->getDayOfYear();   // 225
echo $time->getWeekOfMonth(); // 2
echo $time->getWeekOfYear();  // 33
echo $time->getTimestamp();   // 1471018523 - UNIX timestamp
echo $time->getQuarter();     // 3

echo $time->dayOfWeek;   // 6
echo $time->dayOfYear;   // 225
echo $time->weekOfMonth; // 2
echo $time->weekOfYear;  // 33
echo $time->timestamp;   // 1471018523
echo $time->quarter;     // 3

getAge()

Returns the age, in years, of between the Time’s instance and the current time. Perfect for checking the age of someone based on their birthday:

<?php

$time = Time::parse('5 years ago');

echo $time->getAge(); // 5
echo $time->age;      // 5

getDST()

Returns boolean true/false based on whether the Time instance is currently observing Daylight Savings Time:

<?php

echo Time::createFromDate(2012, 1, 1)->getDst(); // false
echo Time::createFromDate(2012, 9, 1)->dst;      // true

getLocal()

Returns boolean true if the Time instance is in the same timezone as the application is currently running in:

<?php

echo Time::now()->getLocal();    // true
echo Time::now('Europe/London'); // false

getUtc()

Returns boolean true if the Time instance is in UTC time:

<?php

echo Time::now('America/Chicago')->getUtc(); // false
echo Time::now('UTC')->utc;                  // true

getTimezone()

Returns a new DateTimeZone object set the timezone of the Time instance:

<?php

$tz = Time::now()->getTimezone();
$tz = Time::now()->timezone;

echo $tz->getName();
echo $tz->getOffset();

getTimezoneName()

Returns the full timezone string of the Time instance:

<?php

echo Time::now('America/Chicago')->getTimezoneName(); // America/Chicago
echo Time::now('Europe/London')->timezoneName;        // Europe/London

Setters 

The following basic setters exist. If any of the values set are out of range, an InvalidArgumentExeption will be thrown.

Note

All setters will return a new Time instance, leaving the original instance untouched.

Note

All setters will throw an InvalidArgumentException if the value is out of range.

<?php

$time = $time->setYear(2017);
$time = $time->setMonth(4);       // April
$time = $time->setMonth('April');
$time = $time->setMonth('Feb');   // February
$time = $time->setDay(25);
$time = $time->setHour(14);       // 2:00 pm
$time = $time->setMinute(30);
$time = $time->setSecond(54);

setTimezone()

Converts the time from it’s current timezone into the new one:

<?php

$time  = Time::parse('13 May 2020 10:00', 'America/Chicago');
$time2 = $time->setTimezone('Europe/London'); // Returns new instance converted to new timezone

echo $time->getTimezoneName();  // American/Chicago
echo $time2->getTimezoneName(); // Europe/London

echo $time->toDateTimeString();  // 2020-05-13 10:00:00
echo $time2->toDateTimeString(); // 2020-05-13 18:00:00

setTimestamp()

Returns a new instance with the date set to the new timestamp:

<?php

$time  = Time::parse('May 10, 2017', 'America/Chicago');
$time2 = $time->setTimestamp(strtotime('April 1, 2017'));

echo $time->toDateTimeString();  // 2017-05-10 00:00:00
echo $time2->toDateTimeString(); // 2017-04-01 00:00:00

Modifying the Value 

The following methods allow you to modify the date by adding or subtracting values to the current Time. This will not modify the existing Time instance, but will return a new instance.

<?php

$time = $time->addSeconds(23);
$time = $time->addMinutes(15);
$time = $time->addHours(12);
$time = $time->addDays(21);
$time = $time->addMonths(14);
$time = $time->addYears(5);

$time = $time->subSeconds(23);
$time = $time->subMinutes(15);
$time = $time->subHours(12);
$time = $time->subDays(21);
$time = $time->subMonths(14);
$time = $time->subYears(5);

Comparing Two Times 

The following methods allow you to compare one Time instance with another. All comparisons are first converted to UTC before comparisons are done, to ensure that different timezones respond correctly.

equals()

Determines if the datetime passed in is equal to the current instance. Equal in this case means that they represent the same moment in time, and are not required to be in the same timezone, as both times are converted to UTC and compared that way:

<?php

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->equals($time2); // true

The value being tested against can be a Time instance, a DateTime instance, or a string with the full date time in a manner that a new DateTime instance can understand. When passing a string as the first parameter, you can pass a timezone string in as the second parameter. If no timezone is given, the system default will be used:

<?php

$time1->equals('January 11, 2017 03:50:00', 'Europe/London'); // true

sameAs()

This is identical to the equals() method, except that it only returns true when the date, time, AND timezone are all identical:

<?php

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->sameAs($time2); // false
$time2->sameAs('January 10, 2017 21:50:00', 'America/Chicago'); // true

isBefore()

Checks if the passed in time is before the current instance. The comparison is done against the UTC versions of both times:

<?php

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isBefore($time2); // true
$time2->isBefore($time1); // false

The value being tested against can be a Time instance, a DateTime instance, or a string with the full date time in a manner that a new DateTime instance can understand. When passing a string as the first parameter, you can pass a timezone string in as the second parameter. If no timezone is given, the system default will be used:

<?php

$time1->isBefore('March 15, 2013', 'America/Chicago'); // false

isAfter()

Works exactly the same as isBefore() except checks if the time is after the time passed in:

<?php

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isAfter($time2); // false
$time2->isAfter($time1); // true

Viewing Differences 

To compare two Times directly, you would use the difference() method, which returns a CodeIgniter\I18n\TimeDifference instance. The first parameter is either a Time instance, a DateTime instance, or a string with the date/time. If a string is passed in the first parameter, the second parameter can be a timezone string:

<?php

$time = Time::parse('March 10, 2017', 'America/Chicago');

$diff = $time->difference(Time::now());
$diff = $time->difference(new DateTime('July 4, 1975', 'America/Chicago'));
$diff = $time->difference('July 4, 1975 13:32:05', 'America/Chicago');

Once you have the TimeDifference instance, you have several methods you can use to find information about the difference between the two times. The value returned will be negative if it was in the past, or positive if in the future from the original time:

<?php

$current = Time::parse('March 10, 2017', 'America/Chicago');
$test    = Time::parse('March 10, 2010', 'America/Chicago');

$diff = $current->difference($test);

echo $diff->getYears();   // -7
echo $diff->getMonths();  // -84
echo $diff->getWeeks();   // -365
echo $diff->getDays();    // -2557
echo $diff->getHours();   // -61368
echo $diff->getMinutes(); // -3682080
echo $diff->getSeconds(); // -220924800

You can use either getX() methods, or access the calculate values as if they were properties:

<?php

echo $diff->years;   // -7
echo $diff->months;  // -84
echo $diff->weeks;   // -365
echo $diff->days;    // -2557
echo $diff->hours;   // -61368
echo $diff->minutes; // -3682080
echo $diff->seconds; // -220924800

humanize()

Much like Time’s humanize() method, this returns a string that displays the difference between the times in a human readable format that is geared towards being easily understood. It can create strings like ‘3 hours ago’, ‘in 1 month’, etc. The biggest differences are in how very recent dates are handled:

<?php

$current = Time::parse('March 10, 2017', 'America/Chicago');
$test    = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

$diff = $current->difference($test);

echo $diff->humanize(); // 1 year ago

The exact time displayed is determined in the following manner:

Time difference	Result
$time > 1 year && < 2 years	in 1 year / 1 year ago
$time > 1 month && < 1 year	in 6 months / 6 months ago
$time > 7 days && < 1 month	in 3 weeks / 3 weeks ago
$time > today && < 7 days	in 4 days / 4 days ago
$time > 1 hour && < 1 day	in 8 hours / 8 hours ago
$time > 1 minute && < 1 hour	in 35 minutes / 35 minutes ago
$time < 1 minute	Now

The exact language used is controlled through the language file, Time.php.