# Addition of calendar to intl - Thread: https://externals.io/message/59315 - Original archive: https://news-web.php.net/php.internals/59315 - Started by Gustavo Lopes on 2012-04-02T08:35:35+00:00 - Messages: 12 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #59315 — Gustavo Lopes — 2012-04-02T08:35:35+00:00 URL: https://externals.io/message/59315#59315 Hi I have exposed ICU's Calendar API to PHP via the intl extension. It allows date calculations with Gregorian, Chinese, Coptic, Ethiopic, Hebrew, Indian, Islamic (civil/religious), Japanese, Persian, Taiwan and Thai Buddhist calendars. For a broader overview of its functionality, see: http://icu-project.org/apiref/icu4c/classCalendar.html I have committed already this change: https://github.com/php/php-src/commit/1c16c89b96bb4e02850b198b901feebdb8da2269 Traditionally, these kinds of additions to the intl extension (that mostly exposed 1 to 1 the ICU API) have not been preceded (or even followed) by any discussion; however, Stas expressed the opinion this is not a proper course of action nowadays. Consequently, if anyone has any non-trivial substantive (as opposed to procedural) concern with this change, I will revert the merge and submit an RFC. -- Gustavo Lopes --- ## #59317 — Pierre Joye — 2012-04-02T09:13:02+00:00 URL: https://externals.io/message/59315#59317 · In reply to: #59315 hi Gustavo, Very nice job :) The only thing I really dislike is the procedural API. The prefix "intlcal_" is not very nice, but what I really doubt is the usefulness of the procedural APIs for the Calendar resources. It makes little to no sense to have it as it brings nothing in comparison to the OO version. I know we could have it to be consistent with other part of the intl extension but ... Cheers, > Hi > > I have exposed ICU's Calendar API to PHP via the intl extension. It allows > date calculations with Gregorian, Chinese, Coptic, Ethiopic, Hebrew, Indian, > Islamic (civil/religious), Japanese, Persian, Taiwan and Thai Buddhist > calendars. For a broader overview of its functionality, see: > > http://icu-project.org/apiref/icu4c/classCalendar.html > > I have committed already this change: > > https://github.com/php/php-src/commit/1c16c89b96bb4e02850b198b901feebdb8da2269 > > Traditionally, these kinds of additions to the intl extension (that mostly > exposed 1 to 1 the ICU API) have not been preceded (or even followed) by any > discussion; however, Stas expressed the opinion this is not a proper course > of action nowadays. > > Consequently, if anyone has any non-trivial substantive (as opposed to > procedural) concern with this change, I will revert the merge and submit an > RFC. > > -- > Gustavo Lopes > > -- > > > -- Pierre @pierrejoye | http://blog.thepimp.net | http://www.libgd.org --- ## #59318 — johannes@schlueters.de — 2012-04-02T09:37:24+00:00 URL: https://externals.io/message/59315#59318 · In reply to: #59315 > Hi > > I have exposed ICU's Calendar API to PHP via the intl extension. It allows > date calculations with Gregorian, Chinese, Coptic, Ethiopic, Hebrew, > Indian, Islamic (civil/religious), Japanese, Persian, Taiwan and Thai > Buddhist calendars. For a broader overview of its functionality, see: Basically it is good to have those calender stuff available. I wonder how this relates to our datelib. Can this somehow be integrated, at least for Gregorian calender times, so one can easily convert from one to the other etc.? Ideally we'd just have one API :-) johannes --- ## #59319 — Derick Rethans — 2012-04-02T09:44:17+00:00 URL: https://externals.io/message/59315#59319 · In reply to: #59318 > > > […] > > Basically it is good to have those calender stuff available. I wonder > how this relates to our datelib. Can this somehow be integrated, at > least for Gregorian calender times, so one can easily convert from one > to the other etc.? Ideally we'd just have one API :-) Sadly, when I looked at it last time, the ICU stuff insistent on having a timestamp only as input to their formatting functionality :-/ We'd need to use a few things on the ext/date side to get ICU locale formatting into the date/time stuff. cheers, Derick -- http://derickrethans.nl | http://xdebug.org Like Xdebug? Consider a donation: http://xdebug.org/donate.php twitter: @derickr and @xdebug --- ## #59320 — Gustavo Lopes — 2012-04-02T09:45:46+00:00 URL: https://externals.io/message/59315#59320 · In reply to: #59317 On Mon, 02 Apr 2012 11:13:02 +0200, Pierre Joye wrote: > The only thing I really dislike is the procedural API. The prefix > "intlcal_" is not very nice, but what I really doubt is the usefulness > of the procedural APIs for the Calendar resources. It makes little to > no sense to have it as it brings nothing in comparison to the OO > version. > > I know we could have it to be consistent with other part of the intl > extension but ... > Well, it's mainly a matter of consistency. Every other part if the extension exposes, at least, a procedural API, and most of the time also a OO API. So having only an OO API would be unprecedented. As for the usefulness, I agree it's very little, but the same could be said of the OO API (though the procedural API is, in fact, object oriented and the syntactically OO API is a better fit). Nevertheless, many people actually prefer to use the procedural API. In fact, including two APIs implies some non-trivial work, because you have to declare the functions in two function tables, the arginfo must be different, you have to test both, etc. But since it's already done, the only issue is some extra memory and MINIT work required. In sum, I don't think it hurts much and it helps the extension stay consistent. -- Gustavo Lopes --- ## #59321 — Gustavo Lopes — 2012-04-02T10:07:23+00:00 URL: https://externals.io/message/59315#59321 · In reply to: #59319 > > > […] We could surely add functions that convert between DateTime and IntlCalendar objects (there would be some issues on how tightly the time zones could be integrated; see below). But to have one API is basically near impossible given that PHP does not depend itself on ICU. > Sadly, when I looked at it last time, the ICU stuff insistent on having > a timestamp only as input to their formatting functionality :-/ We'd > need to use a few things on the ext/date side to get ICU locale > formatting into the date/time stuff. > This is not about formatting. This is about these kind of date calculations: * converting timestamps to dates and vice-versa (but not in a human readable fashion, locales affect only the calendar type and minor stuff like when the week or weekend start; you get the date fields by method calls such as $cal->get(IntlCalendar::FIELD_HOUR_OF_DAY)). * Adding and rolling amounts to fields. * Calculating field differences. * Determine weekend onsets and offsets. The formatting and parsing of dates is done with IntlDateFormatter, which accepts DateTime objects, though this "integration" with the date extension could possibly be improved. Going a bit off-topic: I think the problem you have with datefmt_format is that the time zone is specified through the formatter and the one of DateTime is ignored. One could add a new function that creates a formatter with the correct time zone extracted from DateTime, but there's still the problem that ICU cannot use PHP's time zone objects directly, so we'd have to use the identifiers. It could be possible to subclass ICU's TimeZone class to create a ICU TimeZone that would wrap a DateTimeZone, but it would also imply using the C++ API for IntlDateFormatter, which is not the case currently. -- Gustavo Lopes --- ## #59322 — Pierre Joye — 2012-04-02T10:42:29+00:00 URL: https://externals.io/message/59315#59322 · In reply to: #59320 > In sum, I don't think it hurts much and it helps the extension stay > consistent. It can hurt in the sense that the procedural is ugly in this case and nobody sane will ever use it. Introducing useless new functions do not sound like a good move to me :) Cheers, -- Pierre @pierrejoye | http://blog.thepimp.net | http://www.libgd.org --- ## #59449 — Stas Malyshev — 2012-04-08T00:38:46+00:00 URL: https://externals.io/message/59315#59449 · In reply to: #59315 Hi! > I have exposed ICU's Calendar API to PHP via the intl extension. It allows > date calculations with Gregorian, Chinese, Coptic, Ethiopic, Hebrew, > Indian, Islamic (civil/religious), Japanese, Persian, Taiwan and Thai > Buddhist calendars. For a broader overview of its functionality, see: > > http://icu-project.org/apiref/icu4c/classCalendar.html Thank you for you work! On the procedural note, I think it would be much better to follow the procedure like this: 1. Talking to extension maintainer 2. Submitting RFC 3. Announcing on the list 4. Publishing the implementation branch 5. Hopefully, review & improvement 6. Commit I hope the times of "commit huge patches first, discuss them and document later if ever" are behind us. Or at least we should try to put them behind us. As for the API, I'm not sure I understand properly what it is supposed to do (one of the downsides of no RFC). Is it for date calculations? What kinds of calculations you could do? What is IntlGregorianCalendar class - and why there is Gregorian one, but not others? If I wanted to work with Hebrew calendar, how would I do that? What does it do that DateTime doesn't? For the timezones - what is the difference between these timezones and the ones DatTime has - is there something additional that these provide? -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 --- ## #59457 — Gustavo Lopes — 2012-04-08T13:01:42+00:00 URL: https://externals.io/message/59315#59457 · In reply to: #59449 On Sun, 08 Apr 2012 01:38:46 +0100, Stas Malyshev wrote: > > […] > > I hope the times of "commit huge patches first, discuss them and > document later if ever" are behind us. Or at least we should try to put > them behind us. I think the documentation part in this case is not as problematic, because the interface has been thoroughly documented in the ICU project. Most of your next questions can be answered by reading http://userguide.icu-project.org/datetime/calendar > As for the API, I'm not sure I understand properly what it is supposed > to do (one of the downsides of no RFC). Is it for date calculations? > What kinds of calculations you could do? See http://userguide.icu-project.org/datetime/calendar#TOC-Usage > What is IntlGregorianCalendar > class - and why there is Gregorian one, but not others? Because the other type calendars, while existing and been implemented as separate C++ classes in ICU, are not part of the ICU public API. You are supposed to instantiate them through a factory method and use only the generic operations defined in Calendar. GregorianCalendar is the only public subclass. You can instantiate it directly and use specific methods -- get/setGregorianChange (to change the Julian/Gregorian cutoff date) and isLeapYear. > If I wanted to work with Hebrew calendar, how would I do that? By specifying @calendar=hebrew in the locale (either in intl.default_locale or by passing it to the factory method IntlCalendar::createInstance()). > What does it do that DateTime doesn't? Asides from supporting many more types of calendars, it has millisecond precision (for dates not too back into the past or future), field rolling, more control on behavior in DST transitions (since ICU 49) and some localization options (e.g. localized day of week). > For the timezones - what is the difference between these timezones and > the ones DatTime has - is there something additional that these provide? The main drive for creating a IntlTimeZone class was simply to encapsulate ICU TimeZone objects, which the Calendar classes work with. Therefore, the support is limited and only the base ICU class for timezones is exposed, except for the methods that allow changing the TimeZone. ICU allows you to build timezones with arbitrary rules, import/export RFC2445 VTIMEZONE and a lot more, none of which are available with my patch. Still, there is already some functionality that doesn't exist in DateTimeZone, like timezone id canonization, localization of time zone names on 8 different formats and easier searching for timezones according to country and region. -- Gustavo Lopes --- ## #60205 — Stas Malyshev — 2012-04-18T21:54:00+00:00 URL: https://externals.io/message/59315#60205 · In reply to: #59457 Hi! > I think the documentation part in this case is not as problematic, > because the interface has been thoroughly documented in the ICU > project. Most of your next questions can be answered by reading > > http://userguide.icu-project.org/datetime/calendar This is ICU docs, not PHP docs. Most PHP users wouldn't even know where to find it, let alone how to use it applied to PHP. We need something to list the functions and what they do. RFC can serve this role, until proper docs are written, but since you've skipped it, we need some other solution, but without that it will be hard to make use of it effectively. > See http://userguide.icu-project.org/datetime/calendar#TOC-Usage OK, I see but it refers to UDate and operations with it - does it duplicate what we do with DateTime? What would be typical use case - to use DateTime or your calendar functions? Would I have to keep dates in two separate forms? How this interacts with DateTime? > By specifying @calendar=hebrew in the locale (either in > intl.default_locale or by passing it to the factory method > IntlCalendar::createInstance()). That definitely has to be documented somewhere. > The main drive for creating a IntlTimeZone class was simply to > encapsulate ICU TimeZone objects, which the Calendar classes work > with. Therefore, the support is limited and only the base ICU class > for timezones is exposed, except for the methods that allow changing > the TimeZone. ICU allows you to build timezones with arbitrary rules, > import/export RFC2445 VTIMEZONE and a lot more, none of which are > available with my patch. I'd say if we already have this class why not support at least most useful things? I'd find VTIMEZONE support definitely very useful. > Still, there is already some functionality that doesn't exist in > DateTimeZone, like timezone id canonization, localization of time > zone names on 8 different formats and easier searching for timezones > according to country and region. Is there an easy way to get from DateTimeZone to intl one and back (at least for standard ones, custom ones probably won't work)? -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227 --- ## #60211 — Gustavo Lopes — 2012-04-19T07:53:27+00:00 URL: https://externals.io/message/59315#60211 · In reply to: #60205 On Wed, 18 Apr 2012 23:54:00 +0200, Stas Malyshev wrote: > > […] > > This is ICU docs, not PHP docs. Most PHP users wouldn't even know where > to find it, let alone how to use it applied to PHP. We need something to > list the functions and what they do. It's ICU docs, but they're applicable here after doing the obvious substitutions (replace all integer types with PHP's integer, etc.). You can list the functions with php --rc IntlCalendar or similar and then refer to that document for the functions' behavior. Of course, this doesn't replace PHP documentation, but it's not urgent at this stage given PHP 5.5 being one year away and the ICU docs giving almost all information to those who want to play with it. > > […] > > OK, I see but it refers to UDate and operations with it - does it > duplicate what we do with DateTime? What would be typical use case - to > use DateTime or your calendar functions? Would I have to keep dates in > two separate forms? How this interacts with DateTime? "UDate is a scalar value that indicates a specific point in time, independent of calendar system and local time zone. It is stored as the number of milliseconds from a reference point known as the epoch. The epoch is midnight Universal Time Coordinated (UTC) January 1, 1970 A.D. Negative UDate values indicate times before the epoch." (http://userguide.icu-project.org/datetime#TOC-How-ICU-Represents-Dates-Times ) UDate is just a typedef for double, and is represented in PHP with the float type. As for DateTime, IntlGregorianCalendar (a specific type of IntlCalendar) *DOES* duplicate some functionality of DateTime. There are some things DateTime does that IntlGregorianCalendar doesn't (like formatting and parsing, which is done in intl through IntlDateFormatter) and there are things that IntlGregorianCalendar does that DateTime doesn't (refer to my previous e-mails on this thread). I'm working on some interoperability with the two; see https://github.com/cataphract/php-src/commit/e6c4dc8 > > […] > > I'd say if we already have this class why not support at least most > useful things? I'd find VTIMEZONE support definitely very useful. Patches welcome :) More seriously, adding complete support for time zones is time consuming because it implies also supporting the classes with which the subclasses of TimeZone collaborate -- for instance, the several types of DST rules. Maybe it's possible to work around that without compromising having full support in the future -- I'm happy to hear ideas. > > […] > > Is there an easy way to get from DateTimeZone to intl one and back (at > least for standard ones, custom ones probably won't work)? Again, I'm working on that: https://github.com/cataphract/php-src/commit/361cf32 I'll post something to this list for review when I have something ready. -- Gustavo Lopes --- ## #60220 — Christopher Jones — 2012-04-19T18:15:54+00:00 URL: https://externals.io/message/59315#60220 · In reply to: #60211 > > > > […] > > It's ICU docs, but they're applicable here after doing the obvious substitutions (replace all integer types with PHP's integer, etc.). > You can list the functions with php --rc IntlCalendar or similar and then refer to that document for the functions' behavior. Of course, this doesn't replace PHP documentation, but it's not urgent at this stage given PHP 5.5 being one year away and the ICU > docs giving almost all information to those who want to play with it. Hi Gustavo, Can you add at least placeholder stub pages to the PHP docs sooner rather than later? Or even just one page listing the changes? Thanks, Chris -- christopher.jones@oracle.com http://twitter.com/#!/ghrd