DataMapper ORM


Example Application

You can see this feature used in all example application models:

    » models/
    » language/english/

Datamapper ORM can automatically load in a model-specific language file, and then it can set language-specific labels on each field or relationship. When using this method, there is no need to specify the label key in the $validation array.

It uses the built-in CodeIgniter library for localizing. For more information on this library, please see the CodeIgniter manual.

If you want Datamapper ORM to automatically load in the language files, and have different languages available on your website, you will probably need a different CodeIgniter library to handle switching the language before creating any Datamapper ORM models.
Also see Handling Language Changes below.


Recommended Method

The easiest way to add localization is use the following language file standards:


1 2 3 4 5 6 7 8
<?php // Language File for Comment Model $lang['comment_comment'] = 'Comment'; $lang['comment_bug'] = 'Bug'; $lang['comment_user'] = 'User'; /* End of file model_comment_lang.php */ /* Location: ./application/language/english/model_comment_lang.php */

Believe it or not, that's it! You don't even have to load in the language file. You can easily create multiple-languages by duplicating the language files for each model into a different language folder, and loading them as needed.

If you are upgrading from a version of Datamapper ORM older than 1.7.0, make sure you add the new lang_file_format configuration option, and set it to model_${model}.

Alternate Method

If you don't want automatic loading, or you prefer hard-coding the labels, you can also manually set the label field using the format lang:lang_key.

Datamapper ORM will automatically replace that label with the appropriate language value, if it exists. Using this method, you can still have Datamapper ORM automatically load the language file using the lang_file_format property.


class User extends DataMapper {
    var $validation = array(
        'name' => array(
            'label' => 'lang:user.fields.Name',
            'rules' => array('required')

Handling Language Changes

The best solution is to somehow determine the language before loading any models. If you can do that, then simply change $this->config->config['language'] and all models will use that.

However, if you need changing the language dynamically, such as when loading a user's preference, you can use reinitialize_model to to reload the language.

Please read the linked section carefully, however, as it doesn't update other models, or any other already existing objects, so it should be called as early as possible.


Most of the time, simply standardizing your language file settings will be all you need to do. However, Datamapper ORM is very flexible in configuring which files to load, and how to look for the language keys.

Both of the properties can be set globally (in the config file, or on a per-model basis.

Loading the Language File

The language file is specified by the configuration option lang_file_format. If it is not provided, is empty, or the file does not exist, no language file will be loaded by default.

The default format is model_${model}.

The option has two properties that can be used to dynamically change the file name. Please note that these must be specified exactly, including the dollar-sign ($) and braces ({}).

The result of the updated property is passed directly to lang->load(). Note: The actual file name must end in _lang.php.

(If the file does not exist, Datamapper ORM won't attempt load it. This prevents errors when you don't have a language file for a given model.)

Loading the Field Labels

The keys for the field labels is specified by the configuration option field_label_lang_format.

The default format is ${model}_${field}.

In addition to the model and table properties, each field key has an additional property:


Localizing Helper Methods

You can actually use the new localizing tools for more than just field labels. They can also be used to dynamically load in properties based on model, table, and field names at any time, using the following two methods.


Example Application

This feature is used in the __toString method of many models:

    » models/

This method will use the field_label_lang_format property to localize a given $field.


function __toString() {
    return $this->exists() ? $this->name : $this->localize_label('unset');

$object->localize_by_model($key, $field)

This method will automatically replace ${model} and ${table} in the given $key, and return the localized string. If $field is passed, that replaces ${field} in the $key.

This may be useful for loading in other common localized strings. For example, you might use it in an extension like this:

// Returns a localized error string
function localize_error($object, $error) {
    return $object->localize_by_model('${model}_error_${field}', $error);