Thinking Globally About Characters and Dates

"Think globally, act locally." This doesn't just apply to recycling household waste, but to developing Ning Sites as well. Sure, you may only speak one language and exist in one time zone, but Ning users live all over the place. We've set things up so the Playground can accommodate multiple languages and time zones, but you need to do your part in your sites to ensure global support as well.

All HTML pages emitted by the Ning Playground are encoded as UTF-8. This means that your programs can expect that submitted form data will be encoded as UTF-8. It also means that generated output should be encoded as UTF-8.

When you put submitted UTF-8 encoded form data into the content store, it'll come back out as UTF-8 encoded data. This is not surprising. It means that someone can submit a form with characters in Chinese, Arabic, English, or pretty much any other alphabet. When you save that data and redisplay it, it'll still look the same.

One area where you have to exercise some extra caution with UTF-8 strings is entity encoding. PHP's htmlentities() function assumes by default that the data it is escaping is encoded not as UTF-8 but a different encoding format (ISO-8859-1). So you need to tell htmlentities() explicitly to treat the string it's escaping as UTF-8. The following example shows how to do that.

$safe = htmlentities($unsafe,ENT_QUOTES,'UTF-8');

Example: UTF-8-aware entity encoding

The second argument to htmlentities() tells it to escape single and double quotes. The third argument (the important one) tells it to treat the $unsafe string as UTF-8 encoded instead of ISO-8859-1.

If you're escaping content object attributes with the h() transformer, don't worry about any of this - h() automatically does the right thing and treats the string it's escaping as UTF-8 encoded.

Another tricky thing about UTF-8 strings is that for many non-Western characters, one character might take up more than one byte. So functions like strlen(), which counts bytes, not characters, don't always return the correct result. PHP's support for this sort of thing right now is kind of spotty. We've enabled the mbstring extension, which helps a bit. The next version of PHP will have much better support for UTF-8 and different character sets. When it's ready for prime time, we'll upgrade to it.

Aside from character encoding, you also need to pay attention to how you handle dates and times. They should be stored in content object attributes of type XN_Attribute::DATE. The system is currently very persnickety about the formatting of a date stamp that you supply as a content object attribute. A date attribute value must look like a complete ISO 8601 date, as specified at http://www.w3.org/TR/NOTE-datetime.

"Complete" means that you must specify year, month, day, hour, minute, second, and a timezone offset indicator. The timezone offset indicator can either be Z (meaning UTC - Greenwich Mean Time), +HH:MM (meaning a positive offset of HH hours and MM minutes from UTC), or -HH:MM (meaning a negative offset from UTC.)

The following examples show some sample valid datestamps.

2005-03-10T12:24:14Z
(12:24:14 PM on March 3, 2005 - UTC)

2005-03-10T12:24:14+05:00
(12:24:14 PM on March 3, 2005 - 5 hours ahead of UTC)

2005-03-10T12:24:14-03:00
(12:24:14 PM on March 3, 2005 - 3 hours behind  UTC)

Example: Valid Datestamps

And the following are some sample invalid datestamps.

2005-03
2005-03-10
(Neither of these are complete.)

2005-03-10 12:24:14Z
(Missing the literal "T" between the day and the hour)

2005-03-10T12:24:14
(Missing a timezone offset specifier)

2005-03-10T12:24:14 05:00
(Missing a + or a - before the timezone offset)

Example: Invalid Datestamps

If you've got an epoch timestamp in PHP (for example as output from time(), mktime(), or strtotime()), convert it into an acceptable formatted date with either of the commands shown in next (assuming you want your timezone offset specifier to be +05:00).

$formatted = strftime('%Y-%m-%dT%H:%M:%S+05:00', $stamp);
$formatted = date('Y-m-d\TH:i:s+05:00',$stamp);

Example: Making a Valid Datestamp

If you store times as UTC times, use the gmstrftime() or gmdate() functions to generate formmatted date/time stamps. These functions assume the epoch timestamp they're handed is in UTC time. Here's how to use them.

$formatted = gmstrftime('%Y-%m-%dT%H:%M:%SZ', $stamp);
$formatted = gmdate('Y-m-d\TH:i:sZ',$stamp);

Example: Making a Valid UTC Datestamp