Date Helper

[lonnieezell]

The date helper should work with DateTime and related classes to provide our date/time functionality. The list of features within the current helper need to be examined. Not all of them are relevant or the best way to do things now.

MUST integrate with whatever solution is determined for our i18n/i10n integrations to default to converting dates/times to current locale, where applicable.

Exact methods still to be determined.

Development Checklist:

• Component(s)
• ... with PHPdocs
• Unit testing
• ... with >80% coverage
• User guide updated
• Classmap integration?
• Securely signed commits
• Conforms to style guide

[mwhitneysdsu]

Here are the current date helper functions, per the CI3 user guide, with type hints added (with some uncorrected errors, especially in default argument types):

• now(string $timezone = null): int returns time() or the equivalent timestamp for $timezone
• mdate(string $datestr = '', int $time = ''): string Format $time using MySQL-style date codes in $datestr
• standard_date(string $fmt = 'DATE_RFC822', int $time = null): string deprecated, Format $time using the format indicated by $fmt, which is a string indicating one of the DateTime format constants
• local_to_gmt(int $time = ''): int Convert local $time to GMT
• gmt_to_local(int $time = '', string $timezone = 'UTC', bool $dst = false): int Convert GMT to local time
• mysql_to_unix(string $time = ''): int Convert MySQL Timestamp to UNIX timestamp
• unix_to_human(int $time = '', bool $seconds = false, string $fmt = 'us'): string Converts a UNIX timestamp to a "human-readable" timestamp in 12-hour (with AM/PM) format ('us') or 24-hour format ('euro').
• human_to_unix(string $datestr = ''): int Reverse of unix_to_human()
• nice_date(string $bad_date = '', string $format = 'U'): string Attempts to convert $bad_date into a date string in the supplied $format or a UNIX timestamp
• timespan(int $seconds = 1, int $time = '', int $units = 7): string Returns a string indicating the time difference between $seconds and $time using strings from date_lang.php to translate the words years, months, weeks, days, hours, minutes, and seconds.
• days_in_month(int $month = 0, int $year = ''): int Returns the number of days in a given month/year.
• date_range(int $unix_start = '', int $mixed = '', bool $is_unix = true, string $format = 'Y-m-d'): array Returns an array of date strings with the given format in the specified period
• timezones(string $tz = '') Returns the timezone offset for the CI timezone indicated by $tz, or an associative array of CI timezones and their offsets.
• timezone_menu(string $default = 'UTC', string $class = '', string $name = 'timezones', $attributes = ''): string Returns an HTML select element containing a list of CI timezones/offsets (the list is provided by timezones())

Many of the documented types or default values in either the documentation or the code comments are incorrect. If I have time, I might submit a PR to fix that in CI3.

In my opinion:

• If the CI timezones are supported at all in CI4, it should be in the form of a compatibility method/function to convert them to PHP timezones.
• The 'us'/'euro' format names for unix_to_human() should be changed, if the function will be kept. The names are misleading, as most would likely believe that they indicate a difference in the placement of the month in the output, and possibly the use of / vs. -, when the only change between the two formats is the use of a 12- or 24-hour format (plus AM/PM in the case of 12-hour).
• Since PHP's DateTime accepts a MySQL timestamp in the constructor, the usefulness of mysql_to_unix() is probably limited (there's a note in the code about MySQL 4.1 compatibility, in which case it would likely be best to use DateTime::createFromFormat())
• Since human_to_unix() expects the format to be the output of unix_to_human(), the 'euro' format would work directly with the DateTime constructor, while the 'us' format would require DateTime::createFromFormat().
• In addition to the individual words, the format of the output of timespan() should be localized
• timezone_menu() is probably better suited to an HTML helper/builder, and the arguments can be condensed, since $name and $class can be included in $attributes. It would also be better to call the appropriate HTML helper/builder function/method to build the select element

It's likely that some of the existing code may be more efficient than creating a DateTime object. Since many of these deal with UNIX timestamps and timezone conversions, anyone attempting to rewrite these functions to utilize DateTime should read the PHP manual entries (and associated reader comments) carefully, since the seemingly obvious choice of creating the DateTime in one timezone, then calling $someDateTime->setTimezone($newTimezome)->format('U') to get the new timestamp is not going to work. This may serve as an explanation for the last three lines of the now() function:

$datetime = new DateTime('now', new DateTimeZone($timezone));
sscanf($datetime->format('j-n-Y G:i:s'), '%d-%d-%d %d:%d:%d', $day, $month, $year, $hour, $minute, $second);
return mktime($hour, $minute, $second, $month, $day, $year);

This also might serve as the best argument for keeping some of these functions, or at least for determining what functionality may be useful in a new date helper.

However, the obvious use of the DateTime::setTimezone() method does work when using formats other than UNIX timestamp for the output, which means the extra conversions can be eliminated if you're formatting date/time information for display or for use in a database (unless the database's field requires a UNIX timestamp).

[lonnieezell]

Very good points, Mat. And thanks for pulling all of that together!

And part of the reason why there's no "Help Wanted" tag on this one yet. I'm pretty sure we'll be incorporating PHP's intl extension and making helper methods for that, but we obviously haven't talked about how it's all going to work together just yet, and whether it's all localized by default if we have localized/non-localized versions, etc.

[prezire]

Anybody here interested in Carbon? I think it has everything for the date and time. "Difference for Humans" is the best. See http://carbon.nesbot.com/docs.

[lonnieezell]

Carbon's great, but you see the response we get every time we suggest using a third-party library on the forums :)

[prezire]

Oh yeah. Can't deny that one.

[sv3tli0]

Carboon is very good tool and in fact it has everything what we need.
But its a standalone lib using Symfony Translation component which is against the logic we have...

Perhaps we can use Carboon fork to migrate it as CodeIgniter Heper making just small changes related to translations and perhaps in merging its 2 classes into 1.

P.S. > If nobody is working on this helper I can work over it.

[kenjis]

I hope you guys see https://github.com/cakephp/chronos.

[prezire]

I'd vote for Carbon as a baseline similar to Kint. Just include minor tweaks to make it CI4. But ey, Chronos looks even shinier than Carbon!

[sv3tli0]

Chronos looks too complicated but their idea to extend DateTimeImmutable is ok for CI 4 as we got PHP 7 to look over (and its added at PHP 5.5).. Our solution should be something in the middle..

[lonnieezell]

Chronos has some nice features, but I haven't jumped on the immutability bandwagon just yet. :)

@sv3tli0 I'd love to have someone tackle this. What plan of attack are you thinking? We need to make sure this works with the Locale, also, if it's set.

[boblennes]

Like Carbon/Chronos but simple!
So we can do add operations like so:

$dt = Dtm::create(2012, 1, 31, 0);

echo $dt->addYears(5); // 2017-01-31 00:00:00
echo $dt->addYear(); // 2018-01-31 00:00:00
echo $dt->addYears(-1); // 2017-01-31 00:00:00
echo $dt->addYears(-5); // 2012-01-31 00:00:00

echo $dt->addMonths(60); // 2017-01-31 00:00:00
echo $dt->addMonth(); // 2017-03-03 00:00:00 equivalent of $dt->month($dt->month + 1); so it wraps
echo $dt->addMonths(-1); // 2017-02-03 00:00:00
echo $dt->addMonths(-60); // 2012-02-03 00:00:00

echo $dt->addDays(29); // 2012-03-03 00:00:00
echo $dt->addDay(); // 2012-03-04 00:00:00
echo $dt->addDays(-1); // 2012-03-03 00:00:00
echo $dt->addDays(-29); // 2012-02-03 00:00:00

echo $dt->addWeekdays(4); // 2012-02-09 00:00:00
echo $dt->addWeekday(); // 2012-02-10 00:00:00
echo $dt->addWeekdays(-1); // 2012-02-09 00:00:00
echo $dt->addWeekdays(-4); // 2012-02-03 00:00:00

echo $dt->addWeeks(3); // 2012-02-24 00:00:00
echo $dt->addWeek(); // 2012-03-02 00:00:00
echo $dt->addWeeks(-1); // 2012-02-24 00:00:00
echo $dt->addWeeks(-3); // 2012-02-03 00:00:00

echo $dt->addHours(24); // 2012-02-04 00:00:00
echo $dt->addHour(); // 2012-02-04 01:00:00
echo $dt->addHours(-1); // 2012-02-04 00:00:00
echo $dt->addHours(-24); // 2012-02-03 00:00:00

echo $dt->addMinutes(61); // 2012-02-03 01:01:00
echo $dt->addMinute(); // 2012-02-03 01:02:00

echo $dt->addSeconds(61); // 2012-02-03 00:01:01
echo $dt->addSecond(); // 2012-02-03 00:01:02
echo $dt->addSeconds(-1); // 2012-02-03 00:01:01
echo $dt->addSeconds(-61); // 2012-02-03 00:00:00

$dt->year = 2015;
$dt->month = 04;
$dt->day = 21;
$dt->hour = 22;
$dt->minute = 32;
$dt->second = 5;

PHP does the rest...