Using the I18N_DateTime Class
Localizing dates and times follows a similar pattern, using the I18N_DateTime class. The class formats dates and times according to a specified locale and format mode, which may be a custom format. The prototypes of the most commonly-used methods are:
- string format([int $timestamp = null], [int $format = null]): Returns the formatted timestamp according to the specified format ($format). The $format argument takes one of these values: I18N_DATETIME_SHORT, I18N_DATETIME_DEFAULT, I18N_DATETIME_MEDIUM, I18N_DATETIME_LONG, I18N_DATETIME_FULL.
- string formatFull([int $timestamp = null]): Returns a fully-formatted timestamp (equivalent to: format($timestamp , I18N_DATETIME_FULL).
- string formatLong([int $timestamp = null]): Returns a long-formatted timestamp (equivalent to: format($timestamp , I18N_DATETIME_LONG).
- string formatShort([int $timestamp = null]): Returns a short-formatted timestamp (equivalent to: format($timestamp , I18N_DATETIME_SHORT).
- string formatDate([int $timestamp = null], [int $format = null]): Returns only the formatted date. If the $format argument is missing the method uses the default format for the current locale.
Other included self-explanatory methods are:
formatDateFull,
formatDateLong, and
formatDateShort. You can format just the time portion of a date/time value using:
 | |
Figure 2. Date/Time Entry Interface: This example uses dropdowns to let users select a date and time, which it then displays appropriately for several different locales. |
- string formatTime([int $timestamp = null], [int $format = null]): This function returns only the formatted time. If the $format argument is missing then the function uses the default format for the current locale.
Similar to dates, other available methods are
formatTimeFull,
formatTimeLong, and
formatTimeShort.
The application in
Listing 2 formats a timestamp (date + time). Again, the application sets up a simple data-entry interface (see
Figure 2), and shows the output for several different locales.
The output of this application is:
es_ES
Date and Time format
format: 07-sep-1980 11:20:30
formatFull: domingo, 07 de septiembre de 1980 11:20 EET +0200
formatLong: 07 septiembre 1980 11:20:30 EET +0200
formatShort: 07/09/80 11:20
Only Date format
formatDate: 07-sep-1980
formatDateFull: domingo, 07 de septiembre de 1980
formatDateLong: 07 septiembre 1980
formatDateShort: 07/09/80
Only Time format
formatTime: 11:20:30
formatTimeFull: 11:20 EET +0200
formatTimeLong: 11:20:30 EET +0200
formatTimeLong: 11:20
===============================================================
fr_FR
Date and Time format
format: 07-sep-1980 11:20:30
formatFull: dimanche, 07 de septembre de 1980 11:20 EET +0200
formatLong: 07 septembre 1980 11:20:30 EET +0200
formatShort: 07/09/80 11:20
Only Date format
formatDate: 07-sep-1980
formatDateFull: dimanche, 07 de septembre de 1980
formatDateLong: 07 septembre 1980
formatDateShort: 07/09/80
Only Time format
formatTime: 11:20:30
formatTimeFull: 11:20 EET +0200
formatTimeLong: 11:20:30 EET +0200
formatTimeLong: 11:20
===============================================================
it_IT
Date and Time format
format: 07 Set 1980 11:20:30
formatFull: Domenica 07 Settembre 1980 11:20
formatLong: 07 Settembre 1980 11:20:30 EET +0200
formatShort: 07/09/80 11:20
Only Date format
formatDate: 07 Set 1980
formatDateFull: Domenica 07 Settembre 1980
formatDateLong: 07 Settembre 1980
formatDateShort: 07/09/80
Only Time format
formatTime: 11:20:30
formatTimeFull: 11:20
formatTimeLong: 11:20:30 EET +0200
formatTimeLong: 11:20
===============================================================
en_US
Date and Time format
format: 07-Sep-1980 11:20:30
formatFull: Sunday, 07 September 1980 11:20 o'clock EET +0200
formatLong: 07 September 1980 11:20:30 EET +0200
formatShort: 07/09/80 11:20
Only Date format
formatDate: 07-Sep-1980
formatDateFull: Sunday, 07 September 1980
formatDateLong: 07 September 1980
formatDateShort: 07/09/80
Only Time format
formatTime: 11:20:30
formatTimeFull: 11:20 o'clock EET +0200
formatTimeLong: 11:20:30 EET +0200
formatTimeLong: 11:20
===============================================================
Defining Custom Formats
To define a custom format for dates and/or times you can use these methods:
- int setFormat([string $format = I18N_DATETIME_DEFAULT]): Defines a custom format for dates and times specified by the $format argument.
- int setDateFormat([string $format = I18N_DATETIME_DEFAULT]): Defines a custom format for dates specified by the $format argument.
- int setTimeFormat([string $format = I18N_DATETIME_DEFAULT]): Defines a custom format for times specified by the $format argument.
The following code shows an example of defining a custom format for dates/times:
<?php
require_once 'I18N/DateTime.php';
//Create an instance of the I18N_DateTime class
$dateTime = new I18N_DateTime( 'en_US' );
// Get the default format
print 'The default current date and time is: ';
$dateTime->setFormat();
print( $dateTime->format() ).'<br />';
//Get the current date and time in a custom format
print 'A custom format for current date and time is: ';
$myFormat = $dateTime->setFormat('d.m.Y , l H:i:s');
print $dateTime->format().'<br />';
//Get the custom date format only
print 'A custom format only for the date is: ';
$myDateFormat = $dateTime->setDateFormat(
'\T\o\d\a\y \i\s l \, d \* m \* y ');
print( $dateTime->formatDate() ).'<br />';
//Get the custom time format only
print 'A custom format only for the time is: ';
$myTimeFormat = $dateTime->setTimeFormat(
'\T\h\e \f\o\r\m\a\t\e\d \c\u\r\r\e\n\t
\t\i\m\e \i\s \: H \H\o\u\r\s i \M\i\n\u\t\e\s \a\n\d s \S\e\c\o\n\d\s');
print( $dateTime->formatTime() ).'<br />';
?>
The output of this application is:
The default current date and time is:
26-Jun-2008 10:40:11
A custom format for current date and time is:
26.06.2008 , Thursday 10:40:11
A custom format only for the date is:
Today is Thursday , 26 * 06 * 08
A custom format only for the time is:
The formatted current time is :
10 Hours 40 Minutes and 11 Seconds
You've seen some base concepts required for internationalization and how to achieve number, currency, date, and time formatting using the I18N package. Using these basic functions, you're well on your way toward building internationalized web sites that display values appropriately for the user's locale.