HerbIgniter User Guide Version 1.7.2

Country Helper

The Country Helper file contains functions that assist in working with foreign governments. This includes linguistics and fiscal policy (currency exchange, language association). It also provides geolocation.

The language routines in this helper I used at PickPark.com - it basically relies on english keywords and files stored in UTF-8. It also uses the Maxmind GeoIP Database when available, and we provide some DB wrappers for storing these objects in tables in your database.

This helper also uses the Xavier Finance free exchange services for international exchange rates. The accuracy is good enough for most applications, but it only supports a subset of its full data set (which you have to pay for). It's probably all you need, but you can always visit them to enhance this.

Loading this Helper

This helper is loaded using the following code:

$this->load->helper('country');

The following functions are available:

lang( line, id='' )

Fetches a language variable and optionally outputs a form label.

Example:

$page->append_body( lang( "Some line." ) );

show_my_language()

Simple function that echos your HTTP_ACCEPT_LANGUAGE $_SERVER superglobal. Usage example:

$my_lang = show_my_language();

find_key_in_file( filename_prefix, code)

Usage: returns a particular code in a simplified keyfile by loading the file, finding the key, returning the value, closing the file and tossing all keys and values read. The keyfiles have extensions that match their respective language codes. File naming examples: thisfile.eng (english), thisfile.spa (spanish), thisfile.ger (german), files that can be kept in a sub-directory and accessed during outputting of a page. This lets you translate your website's content into several different files. It does not filter HTML! This is also a function that is useful if you only need 1 or 2 items from a common file, like 'navigation.eng' or 'index.eng'

Usage example:

$form_name_input_tag_text = find_key_in_file( 'langs/ourfile', 'form_name_input_tag_text' );
echo $form_name_input_tag_text , form_input( ... );

prefetch_keys( filename )

Implements a simple key/value file reading algorithm that reads keys from a file.

Usage example:

$keys = prefetch_keys( "path/to/someKVfile.txt" );
print_r($keys);

prefetch_keys_special( filename )

Option to prefetch and return enumerated array of key/value pairs, indexed by keynames. Currently does not provide any code injection security on keynames or values.

Usage example:

$keys = prefetch_keys_special( "path/to/someKVfile.txt" );
print_r($keys);

find_language( )

ISO 3166 Country Codes; returns ISO codes for countries, with the addition of MaxMind-specific codes for Europe, Asia Pacific Region, Anonymous Proxy and Satellite Provider. Please note that "EU" and "AP" codes are only used when a specific country code has not been designated (see FAQ). Blocking or re-directing by "EU" or"AP" will only affect a small portion of IP addresses. Instead, you should list the countries you want to block/re-direct individually. It has a couple of fallbacks, including one to HTTP_ACCEPT_LANGUAGE. This function is probably the most complete free function on the net. It uses both the ISO country codes, and normalizes them along with Maxmind's codes.

 

Use this function to determine what to name your file (the extension) for a particular language. It returns things like 'eng', 'spa', etc.. Read it in the HerbIgniter source code.

Usage example:

$our_language_code = find_language();

global_lang_prefetch( prefix )

Option to prefetch and return enumerated array of key/value pairs, indexed by keynames. Currently does not provide any code injection security on keynames or values.

Usage example:

$keys = prefetch_keys( "path/to/someKVfile.txt" );
print_r($keys);


prefetch_language( prefix )

Returns a parsed K/V file in the appropriate language, defaulting to US English "prefix.eng" file in the case that none is available for the human language we are detecting.

Usage example:

$translated=prefetch_language( "lang/shoppingcart" );
print_r($translated);

merge_keys( a, b )

Merges multiple files. For instance, if you have a standard navigation area and you have translations for it, use merge_keys() to merge the navigation language file with the content language file.

Usage example:

// Assuming we speak English and it has been detected:
$navigation = prefetch_language( "lang/nav" ); // reads file lang/nav.eng
$indexpage = prefetch_language( "lang/index" ); // reads file lang/index.eng
$translated = merge_keys( $navigation, $indexpage );

show_keyfile( filename )

Option helps you debug bad language files.

Usage example:

$keys = show_keyfile( "path/to/someKVfile.txt" );

fast_lang_block( prefix, code, language )

Option to prefetch and return a key that is in a file. This is sort of like "immediate mode" - its not very optimal except it speeds up development. No checking for supported files, returns empty data and/or throws error when no such file exists.

Usage example:

$key = fast_lang_block( "path/to/someKVfile", "some_key", $our_language_code );
print_r($keys);

safe_lang_block( prefix, key, language )

Option to prefetch and return a key that is in a file. This is sort of like "immediate mode" - its not very optimal except it speeds up development. Checks to see if the language is supported, defaults to English, does not provide code injection protection.

Usage example:

$key = safe_lang_block( "path/to/someKVfile", "some_key", $our_language_code );
print_r($keys);

find_currency( lang, country_name="", region_name="" )

Returns a code like EUR, USD, etc..

Usage example:

$uses_currency = find_currency( find_language() );

exchange( from, to, amount, time )

Uses Xavier Finance to perform a real-time exchange of currency based on a value at a particular time. Since exchange rates are always changing, Xavier helps by providing time-indexed currency exchange rates that will improve your bottom line. Make sure to use the transaction time to set this to the appropriate date when performing this operation on a refund, for instance.

Usage example:$new_amount = exchange( "USD", "EUR", "22.50", "12/22/2009" );

currency_combo( name, selected )

Generates a currency combo box that currently supports about 17 codes. You might want to find another source for your data, but here's a start. This function also works with currency_to_code().

1 => "EUR", //$c["Germany"],
2 => "EUR", //$c["France"],
3 => "GBP", //$c["United Kingdom"],
4 => "EUR", //$c["Italy"],
5 => "EUR", //$c["Luxenburg"],
6 => "EUR", //$c["Netherlands"],
7 => "EUR", //$c["Austria"],
8 => "RUB", //$c["Russia"],
9 => "EUR", //$c["Suisse"],
10 => "USD", //$c["United States"],
11 => "CAD", //$c["Canada"],
12 => "EUR", //$c["Spain"],
13 => "EUR", //$c["Portugal"],
14 => "EUR", //$c["India"],
15 => "USD", //$c["Argentina"] ARS
16 => "USD", //$c["Brazil"] BRL
17 => "EUR" ); //$c["Finland"]

Usage example:

$page->append_body( currency_combo( "currency_form_element", 4 ) );

currency_to_code( currency )

Used in conjunction with currency_combo(), this function converts a numeric value returned from the above combo to a 3-letter currency code (like "USD").

Usage example:

$code = currency_to_code( 3 );

getgeo( ref_table, ref_id, all_or_newest=FALSE, table="maxmind")

Looks for a previous record for a particular DB table (such as "users") and id (like "6") -- the GeoIP log data is in a table is (by default) called 'maxmind' and has the following fields:

"ref_id", $ref_id,
"ref_table", $ref_table,
"geoip", $_SERVER['REMOTE_ADDR'],
"geocountry", $record->country_code,
"geocountry3", $record->country_code3,
"geoname", $record->country_name,
"georegion", $record->region,
"geocity", $record->city,
"geozip", $record->postal_code,
"geolat", $record->latitude,
"geolong", $record->longitude,
"geodma", $record->dma_code,
"geoarea", $record->area_code,
"geotype", GEOIP_STANDARD,
"geolang", $record->country_code

Usage example:

$geoinfo = getgeo();

putgeo( ref_table, ref_id, id=NULL, table="maxmind" )

Stick current information in the DB table that references an IP with a table and id.

Usage example:

putgeo( "users", $user_id );

maxmind( )

Returns the result of a request to Maxmind containing data for the current user/session, similar to getgeo(), but without working directly with a database.

Usage example:

$maxmind_info = maxmind();