Retired Documentation:  You are using the documentation for version 1.7.3 which was retired in 2013. Go here for the latest version documentation or check here for your available upgrades to the latest version.

Localization Class

Calling the Localize Class

ExpressionEngine stores all dates and times in UTC (Universal Coordinated Time), formerly known as GMT (Greenwich Mean Time). The benefit of doing so is that each member of an EE site can choose their own time zone and date localization settings. This permits entries and other information containing dates/times to appear in each member's local time. ExpressionEngine uses the date/time and localization functions available in the Localize class to set and display dates and times throughout the program.

To use the Localize class in your modules you must call the $LOC global in every function that will require the use of the functions contained in the class.

function localization_example()
{
    global $LOC, $IN, $DB;

    $entry_data = array(
                        'entry_id'			=> $entry_id,
                        'title'				=> $title,
                        'url_title'			=> $url_title,
                        'ip_address'		=> $IN->IP,
                        'entry_date'		=> $LOC->now,
                        'year'				=> gmdate('Y', $LOC->now),
                        'month'				=> gmdate('m', $LOC->now),
                        'day'				=> gmdate('d', $LOC->now),
                        'status'			=> 'open'
                        );

    $DB->query($DB->update_string('exp_weblog_titles', $entry_data , "entry_id='$entry_id'"));
}

What time is it now?

$LOC->now will probably be the Localization variable used the most often in any module. Basically, it returns the current UTC (Universal Coordinated Time) and when making an INSERT into the database, this is the time that should be used.

If you need to enter the current day, month, or year into the database you should also inserted into the database as UTC/GMT. To do this, use the PHP function gmdate() with the $LOC->now variable.

$year = gmdate('Y', $LOC->now);

User's Localized Time

$LOC->set_localized_time() is used to return back the current localized time of the user, which is required when displaying dates and times from the database. If the user is a visitor or a member who has not specified their Localization, then the system default will be used.

By default, $LOC->set_localized_time() will return the current time.

if (ereg("^current_time", $key))
{
    $now = $LOC->set_localized_time();
    $tagdata = $TMPL->swap_var_single($key, $LOC->decode_date($val,$now), $tagdata);
}

You can also specify the time in Unix timestamp form, i.e. as from the database.

$d = date('d', $LOC->set_localized_time($query->row['entry_date']));

If you want to set the timezone and/or DST (Daylight Savings Time) independently of the user, you can specify those in the second and third parameter for this tag.

$day = date('d', $LOC->set_localized_time('','-8','n');
// Returns the current day in the PST timezone without DST set.

Date in the URL

$LOC->set_localized_offset() is used when the date is specified in the URL (ex: http://www.site.com/index.php/features/module/2004/07/04/) and we need to determine the current user's offset from GMT in order to pull the correct date range from the database. If the user is a visitor or a member who has not specified their Localization, then the system default will be used.

// Start of day and end of day in Unix timestamp for UTC
$start_time = $LOC->set_gmt(mktime(0, 0, 0, $month, $day, $year));
$end_time = $LOC->set_gmt(mktime(23, 59, 59, $month, $day, $year));

// Checks for Daylight Savings Time (DST)
// Adds or subtracts an hour

if (date("I", $LOC->now) AND ! date("I", $start_time))
{
    $start_time -= 3600;
}
elseif (date("I", $start_time))
{
    $start_time += 3600;
}

if (date("I", $LOC->now) AND ! date("I", $end_time))
{
    $end_time -= 3600;
}
elseif (date("I", $end_time))
{
    $end_time += 3600;
}

// Adds localised offset
$start_time += $LOC->set_localized_offset();
$end_time += $LOC->set_localized_offset();

NOTE: If no day is specified, then the entire month can be selected by using the $LOC->fetch_days_in_month() function.

if ($day == '')
{
    $sday = 1;
    $eday = $LOC->fetch_days_in_month($month, $year);
}
else
{
    $sday = $day;
    $eday = $day;
}

$start_time = $LOC->set_gmt(mktime(0, 0, 0, $month, $sday, $year));
$end_time = $LOC->set_gmt(mktime(23, 59, 59, $month, $eday, $year))

Date Tag Parameters

Your module might allow the use of date parameters in its tag(s) so that only content from a certain date/month/year will be displayed to the users. To do this, the date parameters must first be converted into unixtime for the server and then into UTC time to check against the database time.

$year = ( ! $TMPL->fetch_param('year'))  ? date('Y') : $TMPL->fetch_param('year');
$month = ( ! $TMPL->fetch_param('month')) ? date('m') : $TMPL->fetch_param('month');
$day = ( ! $TMPL->fetch_param('day')) ? date('d') : $TMPL->fetch_param('day');

if (strlen($month) == 1) $month = '0'.$month;

$utc_time = $LOC->set_gmt(mktime(0, 0, 0, $month, $day, $year));

NOTE: If no day is specified, then the entire month can be selected by using the $LOC->fetch_days_in_month() function.

$year = ( ! $TMPL->fetch_param('year'))  ? date('Y') : $TMPL->fetch_param('year');
$month = ( ! $TMPL->fetch_param('month')) ? date('m') : $TMPL->fetch_param('month');
$day = ( ! $TMPL->fetch_param('day')) ? '' : $TMPL->fetch_param('day');

if (strlen($month) == 1) $month = '0'.$month;

if ($day == '')
{
    $sday = 1;
    $eday = $LOC->fetch_days_in_month($month, $year);
}
else
{
    $sday = $day;
    $eday = $day;
}

$start_time = $LOC->set_gmt(mktime(0, 0, 0, $month, $sday, $year));
$end_time = $LOC->set_gmt(mktime(23, 59, 59, $month, $eday, $year))

Human Readable Time

$LOC->set_human_time() formats a Unix/GMT timestamp to the following format: 2003-08-21 11:35 PM. My default, it will use the current time and localize it for the current user. You can also specify a time using the first parameter and by setting the second parameter to FALSE, you can turn off the localization. The third parameter, allows you to add the current seconds past the minute for the human readable time.

$current_user_time = $LOC->set_human_time();
// 2003-06-23 10:35 PM

$current_gmt = $LOC->set_human_time('',FALSE);
// PST timezone for user -8 from GMT
// 2003-06-24 06:35 AM

$time_with_seconds = $LOC->set_human_time('',1,1);
// 2003-06-23 10:35:21 PM

$last_visit = $LOC->set_human_time($row['last_visit']);
// 2003-07-05 9:22 AM

$LOC->convert_human_date_to_gmt() converts a string in the following format to a Unix/GMT timestamp: 2003-08-21 11:35 PM. This function uses the set_localized_offset() function to make sure the returned timestamp is in returned for UTC/GMT.

$entry_date = 2003-06-23 10:35 PM
$entry_UTC_time = $LOC->convert_human_date_to_gmt($entry_date);

Foreign Dates

Whenever possible in an ExpressionEngine user interface, you should use numbers opposed to written text to specify months and specific days. However, for displaying content, ExpressionEngine uses $LOC->decode_date() to parse the date format string (ex: %y %m %d) for a variable and with the UTC/GMT timestamp it will output the correct text according to the language and timezone specified in the user's localization preferences.

$join_date = $LOC->decode_date($date_format, $row['join_date']);

If part of an ExpressionEngine variable, you can simply send the variable to the function, and it will parse out the date format string automatically for you.

foreach ($TMPL->var_single as $key => $val)
{
    if (ereg("^current_time", $key))
    {
        $tagdata = $TMPL->swap_var_single($key, $LOC->decode_date($val,$LOC->now), $tagdata);
    }
}

The Location class has some predefined formatting strings that work in conjunction with $LOC->decode_date(), available in the array: $LOC->format

'DATE_ATOM'		=>	'%Y-%m-%dT%H:%i:%s%Q',
'DATE_COOKIE'		=>	'%l, %d-%M-%y %H:%i:%s UTC',
'DATE_ISO8601'	=>	'%Y-%m-%dT%H:%i:%s%O',
'DATE_RFC822'		=>	'%D, %d %M %y %H:%i:%s %O',
'DATE_RFC850'		=>	'%l, %d-%M-%y %H:%m:%i UTC',
'DATE_RFC1036'	=>	'%D, %d %M %y %H:%i:%s %O',
'DATE_RFC1123'	=>	'%D, %d %M %Y %H:%i:%s %O',
'DATE_RFC2822'	=>	'%D, %d %M %Y %H:%i:%s %O',
'DATE_RSS'		=>	'%D, %d %M %Y %H:%i:%s %O',
'DATE_W3C'		=>	'%Y-%m-%dT%H:%i:%s%Q'

An example usage would be:

$atom_date = $LOC->decode_date($LOC->format['DATE_ATOM'], $LOC->now);

Timezone Menu

If, for some reason, you need to create a timezone menu for your module, then you can use the $LOC->timezone_menu() function, and it will automatically create a form select list with the name 'server_timezone'. You can set the current or default value using the first parameter. Check the zones() function in the Localize class file for acceptable values.

$time_menu = $LOC->timezone_menu('UTC');
// UTC/GMT is selected (0)

$time_menu = $LOC->timezone_menu('UP8');
// PST is selected (-8)

$time_menu = $LOC->timezone_menu('UM2');
// MAST is selected (+2)

Top of Page