13.2. Standards and Formats

The internals of a web application don't care about cultural particularities. Databases, for instance, use international standards to store dates, amounts, and so on. But when data is sent to or retrieved from users, a conversion needs to be made. Users won't understand timestamps, and they will prefer to declare their mother language as Français instead of French. So you will need assistance to do the conversion automatically, based on the user culture.

13.2.1. Outputting Data in the User's Culture

Once the culture is defined, the helpers depending on it will automatically have proper output. For instance, the format_number() helper automatically displays a number in a format familiar to the user, according to its culture, as shown in Listing 13-3.

Listing 13-3 - Displaying a Number for the User's Culture

<?php use_helper('Number') ?>

<?php $sf_user->setCulture('en_US') ?>
<?php echo format_number(12000.10) ?>
 => '12,000.10'

<?php $sf_user->setCulture('fr_FR') ?>
<?php echo format_number(12000.10) ?>
 => '12 000,10'

You don't need to explicitly pass the culture to the helpers. They will look for it themselves in the current session object. Listing 13-4 lists helpers that take into account the user culture for their output.

Listing 13-4 - Culture-Dependent Helpers

<?php use_helper('Date') ?>

<?php echo format_date(time()) ?>
 => '9/14/06'

<?php echo format_datetime(time()) ?>
 => 'September 14, 2006 6:11:07 PM CEST'

<?php use_helper('Number') ?>

<?php echo format_number(12000.10) ?>
 => '12,000.10'

<?php echo format_currency(1350, 'USD') ?>
 => '$1,350.00'

<?php use_helper('I18N') ?>

<?php echo format_country('US') ?>
 => 'United States'

<?php format_language('en') ?>
 => 'English'

<?php use_helper('Form') ?>

<?php echo input_date_tag('birth_date', mktime(0, 0, 0, 9, 14, 2006)) ?>
 => input type="text" name="birth_date" id="birth_date" value="9/14/06" size="11" />

<?php echo select_country_tag('country', 'US') ?>
 => <select name="country" id="country"><option value="AF">Afghanistan</option>
      ...
      <option value="GB">United Kingdom</option>
      <option value="US" selected="selected">United States</option>
      <option value="UM">United States Minor Outlying Islands</option>
      <option value="UY">Uruguay</option>
      ...
    </select>

The date helpers can accept an additional format parameter to force a culture-independent display, but you shouldn't use it if your application is internationalized.

13.2.2. Getting Data from a Localized Input

If it is necessary to show data in the user's culture, as for retrieving data, you should, as much as possible, push users of your application to input already internationalized data. This approach will save you from trying to figure out how to convert data with varying formats and uncertain locality. For instance, who might enter a monetary value with comma separators in an input box?

You can frame the user input format either by hiding the actual data (as in a select_country_tag()) or by separating the different components of complex data into several simple inputs.

For dates, however, this is often not possible. Users are used to entering dates in their cultural format, and you need to be able to convert such data to an internal (and international) format. This is where the sfI18N class applies. Listing 13-5 demonstrates how this class is used.

Listing 13-5 - Getting a Date from a Localized Format in an Action

$date= $this->getRequestParameter('birth_date');
$user_culture = $this->getUser()->getCulture();

// Getting a timestamp
$timestamp = sfI18N::getTimestampForCulture($date, $user_culture);

// Getting a structured date
list($d, $m, $y) = sfI18N::getDateForCulture($date, $user_culture);