Introducing an international calendar class in the PHP international component

Internationalized Calendar Class in PHP

In the internationalized component of PHP, there is also a date operation class that we do not commonly use, which is the calendar operation kind. It is said to be a calendar, but in fact most of it still operates on date and time, and is generally mainly used for date formatting and comparison. But usually we directly use date-related functions or DateTime-related classes to operate date-related functions, which is more convenient and flexible than this set of functions. Of course, for the purpose of learning, let’s take a brief look at it.

Formatting time

First let’s start with the formatting time.

$cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
var_dump(get_class($cal), IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
// string(21) "IntlGregorianCalendar"
// string(66) "2020年11月18日星期三 格林尼治标准时间 上午12:58:14"

$cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin');
var_dump(get_class($cal1), IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'));
// string(21) "IntlGregorianCalendar"
// string(41) "2013 Februar 28 00:01:02 Deutschland Zeit"

The createInstance() method of the IntlCalendar class will return an IntlCalendar object, and its parameters are optional, but must be of type TimeZone. The fromDateTime() method also generates an IntlCalendar object, but it can set a DateTime object or a date type string as a parameter.

As you can see, after using the get_class() method on the returned object, we can see that what is actually returned is an IntlGregorianCalendar Gregorian calendar object. At this time, you can use the formatObject() method of the IntlDateFormatter class to format the output content. It can specify the region. Different regional settings will display different formatting language results.

Return timestamp

echo IntlCalendar::getNow(), PHP_EOL; // 1605661094417

I won’t explain much, but this static method returns a timestamp with milliseconds.

Time zone related settings

As long as the internationalization-related functions are related to the time zone TimeZone, the calendar class is no exception.

ini_set('intl.default_locale', 'de_DE');
ini_set('date.timezone', 'Europe/Berlin');
$cal = IntlCalendar::createInstance();
print_r($cal->getTimeZone());
// IntlTimeZone Object
// (
//     [valid] => 1
//     [id] => Europe/Berlin
//     [rawOffset] => 3600000
//     [currentOffset] => 3600000
// )

echo $cal->getLocale(Locale::ACTUAL_LOCALE), PHP_EOL; // de
echo $cal->getLocale(Locale::VALID_LOCALE), PHP_EOL; // de_DE

Use getTimeZone() to get the current time zone information. There is no difference between getLocale() and the getLocale() method of other related functional classes in our previous article. You can take a look at what we have said before. Of course, in addition to ini_set(), this TimeZone property can also be modified directly through the setTimeZone() method of the object.

ini_set('intl.default_locale', 'zh_CN');
ini_set('date.timezone', 'Asia/Shanghai');
$cal = IntlCalendar::createInstance();
print_r($cal->getTimeZone());
// IntlTimeZone Object
// (
//     [valid] => 1
//     [id] => Asia/Shanghai
//     [rawOffset] => 28800000
//     [currentOffset] => 28800000
// )

$cal->setTimeZone('UTC');
print_r($cal->getTimeZone());
// IntlTimeZone Object
// (
//     [valid] => 1
//     [id] => UTC
//     [rawOffset] => 0
//     [currentOffset] => 0
// )

echo $cal->getLocale(Locale::ACTUAL_LOCALE), PHP_EOL; // zh
echo $cal->getLocale(Locale::VALID_LOCALE), PHP_EOL; // zh_Hans_CN

Calendar related operations

Time field maximum and minimum value related information

What does this mean? Let’s look at the code first.

$cal = IntlCalendar::fromDateTime('2020-02-15');
var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29
var_dump($cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //31
var_dump($cal->getActualMinimum(IntlCalendar::FIELD_DAY_OF_MONTH)); //1
var_dump($cal->getMinimum(IntlCalendar::FIELD_DAY_OF_MONTH)); //1
var_dump($cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH));// 28 

$cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28
var_dump($cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //31
var_dump($cal->getActualMinimum(IntlCalendar::FIELD_DAY_OF_MONTH)); //1
var_dump($cal->getMinimum(IntlCalendar::FIELD_DAY_OF_MONTH)); //1
var_dump($cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH));// 28

What the hell is this bunch upstairs? In fact, these methods return the maximum and minimum values ​​of the specified parameter field content. For example, what we are looking at is FIELD_DAY_OF_MONTH, which is how many days there are in the month. getActualMaximum() returns the actual value. For example, February 2020 has 29 days. getMaximum() returns the maximum value of the normal month, which is 31. getActualMinimum() and getMinimum() return the actual minimum value and the normal minimum value, which are both 1 for the month, and there will definitely be 1 day in each month. The getLeastMaximum() method is to obtain the minimum local maximum value of the field. How to understand it? The minimum number of days in February is 28 days, and its local maximum is 28 days, while other months have 30 and 31 days.

Start date of the week

This function is mainly used to set the day of the week when the start date of the week is. For example, for international standard time in Europe and the United States, Monday is not the beginning of the week, but Sunday is the first day of the week. You can find this problem in various calendar applications.

$cal = IntlCalendar::createInstance();
$cal->set(2020, 5, 30);
var_dump($cal->getFirstDayOfWeek()); // 1
echo IntlDateFormatter::formatObject($cal, <<<EOD
&#39;local day of week: &#39;cc&#39;
week of month    : &#39;W&#39;
week of year     : &#39;ww
EOD
), PHP_EOL;
// local day of week: 3
// week of month    : 5
// week of year     : 27

In the current time zone, the result returned by our getFirstDayOfWeek() is 1, that is, Monday is the starting point of the week, and the day of the week is calculated from 0. The set() method can set a specific date. Please note that the month also starts from 0. We then use IntlDateFormatter::formatObject() to output the day of the week, the week of the month, and the week of the current year. Here we set June 30, 2020. The current date represented by 'cc' is Thursday in the middle of the week, which is the fourth day of the week (not the specified June 30, which is when we run the code time, so that we can view it after modification), the current week is the fifth week in the current month, and the current week is the 27th week in the whole year. What if we change the time this week starts?

$cal->setFirstDayOfWeek(3);
var_dump($cal->getFirstDayOfWeek());  // int(5)
echo IntlDateFormatter::formatObject($cal, <<<EOD
&#39;local day of week: &#39;cc&#39;
week of month    : &#39;W&#39;
week of year     : &#39;ww
EOD
), PHP_EOL;
// local day of week: 1
// week of month    : 6
// week of year     : 27

Well, 'cc' has become 1, and it is currently Monday. We are now in week 6 of the current month, since we now start the week on Thursday.

Calendar comparison

Calendar object comparison

$cal1 = IntlCalendar::createInstance();
$cal2 = IntlCalendar::createInstance();
var_dump($cal1->equals($cal2)); // bool(true)
$cal2->setTime($cal1->getTime() + 1);
var_dump($cal1->equals($cal2)); // bool(false)

This is relatively simple. The properties inside the calendar object are different. Of course, the result returned by the equals() method is false.

Calendar object difference

In addition to comparing calendar objects, you can also obtain the difference information between two calendar times.

$cal1 = IntlCalendar::fromDateTime('2019-1-29 09:00:11');
$cal2 = IntlCalendar::fromDateTime('2020-03-01 09:19:29');
$time = $cal2->getTime();

echo "之前的时间: ", IntlDateFormatter::formatObject($cal1), "\n";
// 之前的时间: 2019年1月29日 上午9:00:11

printf(
    "两个时间的差别： %d year(s), %d month(s), "
  . "%d day(s), %d hour(s) and %d minute(s)\n",
    $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
    $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
);
// 两个时间的差别： 1 year(s), 1 month(s), 1 day(s), 0 hour(s) and 19 minute(s)


echo "之后的时间: ", IntlDateFormatter::formatObject($cal1), "\n";
// 之后的时间: 2020年3月1日 上午9:19:11

You can see that using the fieldDifference() method you can get information related to the calendar object and the comparison date. It should be noted that after using fieldDifference(), all the original calendar objects become new date information.

Other information

View the regional setting keyword value set

print_r(iterator_to_array(IntlCalendar::getKeywordValuesForLocale('calendar', 'zh_CN', true)));
// Array
// (
//     [0] => gregorian
//     [1] => chinese
// )
print_r(iterator_to_array(IntlCalendar::getKeywordValuesForLocale('calendar', 'zh_CN', false)));
// Array
// (
//     [0] => gregorian
//     [1] => chinese
//     [2] => japanese
//     [3] => buddhist
//     [4] => roc
//     [5] => persian
//     [6] => islamic-civil
//     [7] => islamic
//     [8] => hebrew
//     [9] => indian
//     [10] => coptic
//     [11] => ethiopic
//     [12] => ethiopic-amete-alem
//     [13] => iso8601
//     [14] => dangi
//     [15] => islamic-umalqura
//     [16] => islamic-tbla
//     [17] => islamic-rgsa
// )

The first parameter of the getKeywordValuesForLocale() method can only be fixed to the calendar, followed by filling in the relevant areas. The content returned is the relevant word value information supported by the current language environment.

Regional Language Type

$cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
var_dump($cal->getType());
// string(19) "ethiopic-amete-alem"

$cal = new IntlGregorianCalendar();
var_dump($cal->getType());
// string(9) "gregorian"

Obviously, the getType() method returns the type of the specified language area information.

滚动日历

var_dump(IntlDateFormatter::formatObject($cal)); // string(31) "2020年11月18日 上午9:14:59"
$cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true);
var_dump(IntlDateFormatter::formatObject($cal)); // string(31) "2020年11月19日 上午9:14:59"

使用 roll() 方法可以滚动或者说是卷动日历，在这里我们将日历滚动一天，也就是加了一天的时间。

转换为 DateTime 对象

var_dump($cal->toDateTime());
// object(DateTime)#4 (3) {
//     ["date"]=>
//     string(26) "2020-11-19 09:14:59.000000"
//     ["timezone_type"]=>
//     int(3)
//     ["timezone"]=>
//     string(13) "Asia/Shanghai"
//   }

使用 toDateTime() 方法就可以将当前的 IntlCalendar 对象转换成 DateTime 对象。

当前系统中支持的所有区域信息

print_r(IntlCalendar::getAvailableLocales());
// Array
// (
//     [0] => af
//     [1] => af_NA
//     [2] => af_ZA
//     [3] => agq
//     [4] => agq_CM
//     [5] => ak
//     [6] => ak_GH
//     [7] => am
//     [8] => am_ET
//     [9] => ar
//     ……
//     ……

getAvailableLocales() 返回的是当前系统中所有支持可用的 Locale 信息。

总结

关于日历类其实还有很多方法函数，但是看得人非常头晕，英文解释不多，资料也不清晰，所以这里就是简单的列举了一些内容。大家还是报以学习的心态了解即可，当需要使用到的时候可以快速地想起还这些功能就可以了。

推荐学习：《PHP视频教程》

The above is the detailed content of Introducing an international calendar class in the PHP international component. For more information, please follow other related articles on the PHP Chinese website!