You might consider writing your own functions to deal with this type of situation, but this is not very appealing, not only because it is extra work for a German-language site but because the same task would then have to be repeated for each language. Fortunately, a much better way to accomplish this task exists. You can use the setlocale() function to change PHP’s lan- guage and related settings in a number of ways. Here you are concerned primarily with how dates and times are represented, but if internationalization is of any concern to you in your work with PHP, you should investigate this function more thoroughly. setlocale() takes two arguments: a category (a predefined constant) and a language code (a string). To localize time and date settings, you can use either LC_ALL or LC_TIME for the category. You can determine whether the locale was set successfully by testing the return value of setlocale(), which is either the language string on success or FALSE on failure. The languages or locales actually supported will vary from system to system; if you cannot find a value for a desired language or locale, check with your system administrator or consult the operating sys- tem documentation. On Unix systems, you can often find out what is supported by examining the contents of the /usr/share/locale directory. On Windows, use Regional Settings in the Control Panel. If you do not know ahead of time what is supported, you can pass multiple language/locale strings to setlocale(), and PHP will test each one in succession until (you hope) one is used successfully. For example: <?php if($lc = setlocale(LC_ALL, "de_DE", "de_DE@euro", "deu", "deu_deu", "german")) echo "<p>Locale setting is \"$lc\".</p>"; else echo "<p>Couldn't change to a German locale.</p>"; ?> Once you have set the locale, you are ready to output dates and times in the target lan- guage without resorting to brute-force translation (and possible transliteration). However, you cannot use date() for this. Instead, you must use a separate function, strftime(). This function is similar to date() in that it takes a format string and an optional timestamp as arguments. Unfortunately, the similarity ends there, because the formatting characters are quite unlike those used by date(). Table 5-3 lists the characters you are most likely to need, arranged by the part of the date or time they represent. Note that not all of these are available on all platforms, and Windows has some of its own. See http://msdn.microsoft.com/ library/en-us/vclib/html/_crt_strftime.2c_.wcsftime.asp for a complete listing. Table 5-3. Format Characters Used by the strftime() Function Character Description Day %A Full weekday name. %a Abbreviated weekday name. %u Weekday number (1 = Monday, 7 = Saturday). %d Day of the month, with leading zero. 5-9 ■ DISPLAYING TIMES AND DATES IN OTHER LANGUAGES220 5092_Ch05_FINAL 8/26/05 9:51 AM Page 220 Character Description %e Day of the month, with leading space. %j Day of the year (001–366). Note that numbering begins with 1 and not 0. Week %U Number of the week of the year, with Sunday as the first day of the week. %V ISO-8601 number of the week of the year, with Monday as the first day of the week (01–53). %W Number of the week of the year, with Monday as the first day of the week (decimal number). Month %B Full name of the month. %b or %h Abbreviated name of the month. %m Number of the month, with leading zero. Year %g Two-digit year for ISO-8601 week of the year. %G Four-digit year for ISO-8601 week of the year. %y Two-digit year. %Y Four-digit year. Hour %H Hour (00–23). %I Hour (01–12) Minute %M Minute. Second %S Second. Full Date and/or Time %c Preferred date and time representation for the current locale. %D Current date; equivalent to %m/%d/%y. %p a.m./p.m. indicator. %R Time in 24-hour notation. %r Time in 12-hour (am/pm) notation. %T Current time; equivalent to %H:%M:%S. %x Preferred date representation. %X Preferred time representation. %z or %Z Time zone. Formatting Characters %n New line. %t Ta b. %% The percent character. 5-9 ■ DISPLAYING TIMES AND DATES IN OTHER LANGUAGES 221 5092_Ch05_FINAL 8/26/05 9:51 AM Page 221 Now you are ready to put this together in a simple working example. Actually, since browsers have problems displaying more than one character set in a single page, we will use three examples. The Code <?php if($loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu')) { echo "<p>Preferred locale for German on this system is \"$loc_de\".<br />"; echo 'Guten Morgen! Heute ist ' . strftime('%A %d %B %Y', mktime()) . ".</p>\n"; } else echo "<p>Sorry! This system doesn't speak German.</p>\n"; ?> <?php if($loc_ru = setlocale(LC_ALL, 'ru_RU.utf8', 'rus_RUS.1251', 'rus', 'russian')) { echo "<p>Preferred locale for Russian on this system is \"$loc_ru\".<br />\n"; echo '&#x0414&#x043E&#x0431&#x0440&#x043E&#x0435 ' . '&#x0423&#x0442&#x0440&#x043E! ' . '&#x0421&#x0435&#x0433&#x043E&#x0434&#x043D&#x044F ' . strftime('%A %d %B %Y', mktime()) . ".</p>\n"; } else echo "<p>Couldn't set a Russian locale.</p>\n"; ?> <?php if($loc_zh = setlocale(LC_ALL, 'zh_ZH.big5', 'zh_ZH', 'chn', 'chinese')) { echo "<p>Preferred locale for Chinese on this system is \"$loc_zh\".<br />\n"; echo '???! ??? ' . strftime('%A %d %B %Y', mktime()) . ".</p>\n"; } else { echo "<p>Sorry! No Chinese locale available on this system.</p>\n"; $lc_en = setlocale(LC_TIME, 'en_US', 'english'); echo "<p>Reverting locale to $lc_en.</p>\n"; } ?> 5-9 ■ DISPLAYING TIMES AND DATES IN OTHER LANGUAGES222 5092_Ch05_FINAL 8/26/05 9:51 AM Page 222 How It Works Figure 5-4 shows the output in a web browser from each of these scripts when run on a Windows system that supports German and Russian locales but no Chinese locale. Figure 5-4. Output from the three setlocale()/strftime() examples ■Note LC_TIME changes only the way in which dates and times are reported but does not change other locale-dependent items such as character sets. If you use an English-language locale and need to display dates in a language (German or Spanish, for example) that uses the Latin-1 character set or a close relative such as ISO-8559-1, ISO-8859-15, or Windows-1252, you may be able to use LC_TIME.However, in the case of a language that uses non-Latin characters (such as Russian, Chinese, and some Eastern European languages with special characters not represented in Western European character sets), you will most likely have to use LC_ALL. Be aware that using setlocale() with LC_ALL will change all locale settings, not just those related to dates and times. If you will be working with currency, numbers, or sorting of strings, be sure to check the PHP manual for setlocale() and understand what all the implications might be before doing so. The format of the language string differs between Unix and Windows systems. On Unix systems, this varies somewhat but generally takes the form lc_CC.charset, where lc repre- sents the two-letter language code, CC represents the two-letter country code, and charset is the designation of the character set to be used. (The charset designation—including the period—is often optional.) For example, pt_BR.ISO-18859-1 might be used to represent Brazil- ian Portuguese. On Windows, you can use either Microsoft's three-letter language codes or the names of the languages, for example, deu or german for German-language dates and times. 5-9 ■ DISPLAYING TIMES AND DATES IN OTHER LANGUAGES 223 5092_Ch05_FINAL 8/26/05 9:51 AM Page 223 5-10. Generating Localized GMT/UTC Time and Date Strings It is important to remember that using setlocale() to set LC_ALL or LC_TIME does not handle time zone differences for you, as this example illustrates: <?php $ts = mktime(); echo '<p>' . date('r (T)', $ts) . "</p>\n"; if($loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu')) echo 'Guten Abend! Heute ist ' . strftime('%A %d %B %Y, %H.%M Uhr', $ts) . ".</p>\n"; else echo "<p>Sorry! This system doesn't speak German.</p>\n"; ?> The following shows the output for the date and time in standard format, along with the name of the time zone, and then it shows a greeting, date, and time in German. As you can see here, the time may be in German, but it is not German time that is being reported: Fri, 18 Mar 2005 17:14:30 +1000 (E. Australia Standard Time) Guten Abend! Heute ist Freitag 18 März 2005, 17.14 Uhr. To report local time for any Germans who might be viewing this page, you have to calcu- late the time zone offset yourself: <?php $ts_au = mktime(); // local time in Brisbane (GMT +1000) $ts_de = $ts_au - (9 * 3600); // Berlin time is GMT +0100; difference is 9 hours echo 'Good evening from Brisbane, where it\'s ' . date('H:m \o\n l d m Y', $ts_au) . ".<br />"; setlocale(LC_ALL, 'de_DE', 'german'); echo 'Guten Morgen aus Berlin. Hier ist es ' . strftime('%H.%M Uhr, am %A dem %d %B %Y', $ts_de) . '.'; ?> The output from the previous code snippet should look something this: Good evening from Brisbane, where it's 18:03 on Friday 18 03 2005. Guten Morgen aus Berlin. Hier ist es 09.30 Uhr, am Freitag dem 18 März 2005. 5-10 ■ GENERATING LOCALIZED GMT/UTC TIME AND DATE STRINGS224 5092_Ch05_FINAL 8/26/05 9:51 AM Page 224 To generate a localized GMT/UTC time and date string, you can use the gmstrftime() function. It works in the same way as strftime(), except it produces a date and time string in accordance with GMT/UTC rather than local time. ■Tip For more information about language and other codes that can be used with the setlocale() function, see the following URLs: • C-1766,“Tags for the Identification of Languages”: http://www.faqs.org/rfcs/rfc1766 • ISO-639,“3-Letter Language Codes”: http://www.w3.org/WAI/ER/IG/ert/iso639.htm •You can find identifiers available on Windows systems for languages, countries, and regions here: • MSDN, “Language Strings (Visual C++ Libraries)”: http://msdn.microsoft.com/library/en-us/vclib/html/_crt_language_strings.asp • MSDN, “Run-Time Library Reference: Country/Region Strings”: http://msdn.microsoft.com/library/en-us/vclib/html/_crt_country_strings.asp One final note before moving on: most if not all Hypertext Transfer Protocol (HTTP) head- ers use GMT/UTC dates and times that are expressed in English. Generally speaking, these must conform to the RFC-1123 format ddd, dd mmm yyyy HH:mm:ss GMT, such as Mon, 28 Mar 2005 12:05:30 GMT. Here is an example showing how to generate a Content-Expires header that tells user agents that a page should be considered “stale” exactly ten days after it has been served by your site: header('Expires: ' . gmdate('D, d M Y H:i:s', strtotime("+10 days")) . ' GMT'); The same is true for If-Modified-Since, If-Unmodified-Since, Last-Modified, and other time- and date-sensitive HTTP headers. To generate these programmatically, you should always use gmdate() and not strftime() and not gmstrftime(), as the latter two may contain locale-specific information or be in a language other than English. ■Note For definitions of HTTP 1.1 headers, see http://www.w3.org/Protocols/rfc2616/ rfc2616-sec14.html. 5-11. Obtaining the Difference Between Two Dates As you have already had the chance to see, altering a date by a given interval is not difficult. Getting the difference between two dates is a bit more complicated. 5-11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES 225 5092_Ch05_FINAL 8/26/05 9:51 AM Page 225 The Code <?php $date1 = '14 Jun 2002'; $date2 = '05 Feb 2006'; $ts1 = strtotime($date1); $ts2 = strtotime($date2); printf("<p>The difference between %s and %s is %d seconds.<p>\n", $date1, $date2, $ts2 - $ts1); ?> How It Works The output looks like so: The difference between 14 Jun 2002 and 05 Feb 2006 is 115084800 seconds. This is an answer, and you can verify that it is a correct one (a bit more than three years), but it is not really a good answer—unless you know for certain that your users will not object to performing a bit of long division. Variations and Fixes Let’s create a function that you can use to obtain the difference between two dates and times and to present the results in a manner humans can easily understand. This function, which we will call date_diff(), normally takes one or two arguments, each of which is either an integer representing a timestamp or a time/date string in a format understood by strtotime(). (Actu- ally, it can be called without any arguments, but the results will not be terribly interesting or useful; also, you can set an optional third argument to enable debugging output.) This func- tion returns an array consisting of three elements—two arrays and an integer, which will be described for you in a moment. We are breaking up the code listing here in order to provide some commentary as you read through it, but you can get it in the single file date_diff.php in the chapter5 directory of the code download package that accompanies this book and that you can download for free from the Downloads section of the Apress website at http://www.apress.com/. <?php function date_diff($date1=0, $date2=0, $debug=FALSE) { The first task is to check the argument types passed to this function. (Note that they both default to zero.) For each of the values, you check its type using is_numeric(). If it is a number, you treat it as an integer and thus a timestamp; otherwise, you treat it as a string to be passed to strtotime(). In production, you may want to perform some additional checks (for instance, on a Windows system, you need to make sure that neither of the first two arguments repre- sents a date prior to the Unix epoch), but this is sufficient for the current purposes. 5-11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES226 5092_Ch05_FINAL 8/26/05 9:51 AM Page 226 Once you have decided how to handle the input parameters and have converted any strings to timestamps, you assign the timestamps to the variables $val1 and $val2 and then subtract one from the other. To avoid problems with negative values, you can actually obtain the absolute value of the difference. This value is then assigned to the variable $sec. $val1 = is_numeric($date1) ? $date1 : strtotime($date1); $val2 = is_numeric($date2) ? $date2 : strtotime($date2); $sec = abs($val2 - $val1); // **DEBUG ** if($debug) printf("<p>Date 1: %s Date2: %s</p>\n", date('r', $val1), date('r', $val2)); The reason for getting the absolute value is so that you can pass it to getdate(), assigning the value that is returned by this function to the variable $units. You also create an array named $output, which you will use for storing the data to be returned from this function. $units = getdate($sec); // **DEBUG** if($debug) printf("<pre>%s</pre>\n", print_r($units, TRUE)); $output = array(); Before continuing, let’s see what sort of data $units contains at this point by calling the function with the $debug argument set to TRUE: <?php date_diff('12 Sep 1984 13:30:00', '10 Sep 1984 09:15:45', TRUE'); ?> This is the output: Date 1: Wed, 12 Sep 1984 13:30:00 +1000 Date2: Mon, 10 Sep 1984 09:15:45 +1000 Array ( [seconds] => 15 [minutes] => 14 [hours] => 14 [mday] => 3 [wday] => 6 [mon] => 1 [year] => 1970 [yday] => 2 [weekday] => Saturday [month] => January [0] => 188055 ) 5-11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES 227 5092_Ch05_FINAL 8/26/05 9:51 AM Page 227 We also need to talk about the output from this function. As we have said already, the return value is an array consisting of three elements: components: This is an array whose elements are the difference between the dates when expressed as a single quantity broken down into years, months, days, hours, minutes, and seconds. Given the two dates shown previously, you would expect this to be 0 years, 0 months, 2 days, 4 hours, 14 minutes, and 15 seconds. But some obvious discrepancies exist between those values shown; we will return to this issue and discuss these shortly. elapsed: This element is also an array, whose elements are named for years, months, weeks, days, hours, minutes, and seconds. However, each of these is a stand-alone value; in other words, the elements of this array will—in the case of the dates used previously— make it possible to express the difference as (approximately) .0060 years, or 0.073 months, or 0.31 weeks, or 2.2 days, or 52.24 hours, or 3,134.25 minutes, or 188,055 seconds. order: This is simply an integer value: -1 if the second date is earlier than the first and 1 if otherwise. You will look at the complete output of date_diff() a bit later in this recipe. Right now, we will discuss how to reconcile the output you just saw with what you know ought to go into the array $output["components"]. Keep in mind that what you are doing is treating a value representing elapsed time as though it were a timestamp and using getdate() to get an approximation of the number of years, months, days, and so on, that it breaks down into. Let’s start with the hours, because they are a bit tricky. getdate() handles a timestamp with the same attitude (so to speak) as mktime(), in that the values it returns are calculated in terms of system time. What this means is that the difference in hours between system time and GMT is added to $units["hours"], and you need to subtract the same amount in order to correct for this. You can get the difference in seconds by obtaining date('Z'); then you just divide this amount by 3600 to get the difference in hours and subtract the result from $units["hours"] to find the value for $hours. $hours = $units["hours"] – (date('Z') / 3600); You also have to consider that half the time zones on the planet are negative with respect to GMT, and thus what will actually happen is that some number of hours will be added to $units["hours"]. This means you could end up with a value greater than 24. To handle this possibility, you need to test whether the number of hours is greater than 24; if it is, then you will have to increment the number of days and subtract 24 from $hours: $days = $units["mday"]; while($hours > 23) { $days++; $hours -= 24; } Now you are ready to actually assign values to keys in the $outputs["components"] array. To get an accurate number of years, you need to subtract 1970 (the base year for timestamps) from $units["years"]. 5-11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES228 5092_Ch05_FINAL 8/26/05 9:51 AM Page 228 ■Note If your system uses a time zone west of Greenwich (chiefly, the Americas), you will need to take into account that the Unix epoch will be represented as something such as 31 December 1969 19:00:00 for U.S. Eastern Standard Time (GMT–0500). In this case, the value of the years element would be 1969. Now consider the situation when the time difference between the two dates that were passed to date_diff() is less than one month; getdate() will return a value of 1 for the months, where you actually want a value of 0 (no months elapsed). The same is true of days. Putting this together, you can now assign values to all the elements of $output["components"]: $epoch = getdate(0); // the Unix epoch in the server's local time zone $output["components"] = array( "years" => $units["year"] - $epoch["year"], "months" => $units["mon"], "days" => $days, "hours" => $hours, "minutes" => $units["minutes"], "seconds" => $units["seconds"] ); Let’s look at the second element in $output, the $output["elapsed"] array. This is actually fairly straightforward, since all that is required is to divide the total number of seconds elapsed by the number of seconds in a year, in a month, in a week, and so on, and assign these values appropriately: $output["elapsed"] = array( "years" => $sec / (365 * 24 * 60 * 60), "months" => $sec / (30 * 24 * 60 * 60), "weeks" => $sec / (7 * 24 * 60 * 60), "days" => $sec / (24 * 60 * 60), "hours" => $sec / (60 * 60), "minutes" => $sec / 60, "seconds" => $sec ); Finally, you set $output["order"] equal to -1 if the second date is earlier than the first and to 1 if it is not, and then you return the $output array to the calling code: $output["order"] = $val2 < $val1 ? -1 : 1; return $output; } ?> Let’s test this function with a couple of sample values. Note that you can omit the $debug argument—in fact, you might want to take the debugging portions from the function when using it in production, but we will leave that decision up to you. First we will use print_r() to output a sample array and then write a message that tells the reader exactly how long our last 5-11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES 229 5092_Ch05_FINAL 8/26/05 9:51 AM Page 229 [...]... [years] => 0 [months] => 0 [days] => 13 [hours] => 5 [minutes] => 50 [seconds] => 0 ) [elapsed] => Array ( [years] => 0.036282 343 987823 [months] => 0 .44 14 351 851 851 9 [weeks] => 1.8918 650 793 651 [days] => 13. 243 055 555 556 [hours] => 317.83333333333 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 231 5- 12 ■ PROJECT: CONSTRUCTING AND USING A DATE CLASS [minutes] => 19070 [seconds] => 1 144 200 ) [order] => 1 ) My holiday... but they are really quite straightforward You can see a complete listing of these, as we have adapted them for use in PHP 5, in Figure 5- 5 Figure 5- 5 Base Date class members, showing input parameters and return types 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 233 5- 12 ■ PROJECT: CONSTRUCTING AND USING A DATE CLASS The Date class provides two static methods that we will discuss shortly All the remaining methods... 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 251 5- 13 ■ EXTENDING THE DATE CLASS implement an ECMA-compliant Date class with different internals, and code written against our Date class should still work However, you can leverage the capabilities of the existing class in a new class that extends Date You will call this new class DateExtended, and in it you will provide methods for displaying names and abbreviations... 25 UTC Day of Week: 5 UTC Year: 20 05 UTC Hours: 11 UTC Minutes: 49 UTC Seconds: 37 Value returned by getTimeZoneOffset(): -600 Test date: Sat, 5 April 2003 15: 15: 25 +1000; Date::parse() yields: 1 04 951 97 25 Date::UTC() method: 1 14 752 7000 Using toUTCString(): Fri 25 Mar 20 05 11 :49 :37 UTC Now for some 'set' methods Let's try advancing the date by one day: Sat, 26 Mar 20 05 21 :49 :37 +1000 Now let's try advancing... ch5/Date-Extended.class.inc .php 251 50 92_Ch 05_ FINAL 252 8/26/ 05 9 :51 AM Page 252 5- 13 ■ EXTENDING THE DATE CLASS The Code < ?php // file: Date-Extended.class.inc .php // purpose: provide additional output methods for // the ECMA-compliant Date class (Date.class.inc .php) Since this class extends the existing Date class, you need to include the file containing the Date class definition and use extends Date... isLeapYear() in this fashion more often than not, you can always reimplement it as an instance method In any case, this method does its job by invoking mktime() to create a timestamp for the first day of the year passed to isLeapYear() as $year and using this timestamp as the second argument for a call to date() date('L'), as you will recall from earlier in the chapter, returns 1 if the year is a leap... counterparts, except that the function names are all prefixed with adodb_, and a few of the formatting characters used with date(), gmdate(), strftime(), and gmstrftime() are not supported by their ADOdb analogs However, the library adds some extended functionality for setting and tracking daylight-saving time, so it seems a fair trade You can download this library and read its documentation at http://phplens.com/phpeverywhere/adodb_date_library... incarnations—browser JavaScript, Flash ActionScript, Microsoft JScript, and so on—then you are probably aware that ECMA-262 dates are stored internally as millisecond timestamps That is, an ECMAScript date that complies with the specification is supposed to be stored as a number of thousandths of a second elapsed since the Unix epoch Because PHP does not provide a ready means to obtain milliseconds for any date and... difference to anyone using it, as long as what goes in and what comes out remain the same.) 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 253 5- 13 ■ EXTENDING THE DATE CLASS Unlike the constructor for its parent class, the constructor for DateExtended is simple In fact, all it does is invoke the Date class constructor and pass on any arguments it receives as an array by means of the func_get_args() function... and tuples, as they are known in that language), Perl is handy for string processing, C is good for building data structures, and so on We have always found the Date class provided in 231 50 92_Ch 05_ FINAL 232 8/26/ 05 9 :51 AM Page 232 5- 12 ■ PROJECT: CONSTRUCTING AND USING A DATE CLASS JavaScript (or, more properly, EMCAScript) to offer a simple, unambiguous, no-frills way to work with dates This class, . '&#x 041 4&#x 043 E&#x 043 1&#x 044 0&#x 043 E&#x 04 35 ' . '&#x 042 3&#x 044 2&#x 044 0&#x 043 E! ' . '&#x 042 1&#x 04 35& amp;#x 043 3&#x 043 E&#x 043 4&#x 043 D&#x 044 F. languages, for example, deu or german for German-language dates and times. 5- 9 ■ DISPLAYING TIMES AND DATES IN OTHER LANGUAGES 223 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 223 5- 10. Generating Localized GMT/UTC. 0 .44 14 351 851 851 9 [weeks] => 1.8918 650 793 651 [days] => 13. 243 055 555 556 [hours] => 317.83333333333 5- 11 ■ OBTAINING THE DIFFERENCE BETWEEN TWO DATES230 50 92_Ch 05_ FINAL 8/26/ 05 9 :51 AM Page 230 [minutes]