Country Import Files

Country import files are used to add international country, zone, and address support to your Ãœbercart installation. The structure for these files is still described below, and changes are being made to the checkout, store, and tax systems to encourage international use and development.

For more information, please view the following thread in the Internationalization forum:
http://www.ubercart.org/forum/internationalization/147/getting_started_i...

We've taken some clues from osCommerce here, but I tweaked it a little per tormi's suggestion to use the ISO-3166 standard for country numbers. View the following thread for more information:

http://www.ubercart.org/forum/internationalization/44/country_id_osc_vs...

The second post in the thread has links to the Wikipedia pages of lists and a consolidated list of countries from 2003 as a file attachment. Be sure you're using the most current codes and zones for your country.

You can use boogiebug's port of an osC contribution as a starting list of all the zones for a country. If any are missing, feel free to add them. See his list in this thread:

http://www.ubercart.org/forum/internationalization/533/sql_all_country_c...

Naming an import file:

The name of the country import file is important, as it holds the country ID and version of the current import file. This is to speed the code up just a touch by preventing a bunch of fopen()'s to find out the versions of these files. The name should be all in lower case letters and set per the example below.

    Pattern
  • country-name_country-id_version.cif
    Examples
  • united_states_840_1.cif
  • canada_124_1.cif

country_name should be the name of the country with hyphens and spaces turned into underscores. Any other characters should be omitted. country_id is unique to the country and predetermined. Find your country's ID in ISO-3166 numeric code list (see it here). Omit any leading zeroes, so 004 would become just 4. version should be the latest version of the file. Version numbers start at 1 and increment by 1 every time an update has been made to the country file.

Structure of an import file: (Click here to view the reference page.)

Country import files will be included and executed for installation and updates. Therefore, you must make sure it is valid PHP and starts with <?php on the first line. Do not close your PHP tag at the end of the file. The second line should be // $Id$ for CVS purposes.

An import file is made primarily of three functions, an install function, an update handler, and an uninstall function. These all work with simple hooks where the function names use the pattern country-name_install, country-name_update, and country-name_uninstall respectively. A hook function does not need to be included in the import file if it is empty.

The install function should simply contain code to be executed when the country file is first installed. The function doesn't expect any arguments. This includes code to add a row to the table uc_countries, add the corresponding rows to uc_zones, set the variable for the country's default address format, and perform any other necessary installation procedures. When a user chooses to install the file, this function is executed and a message is displayed letting them know the import completed. You may choose to set other messages during the course of installation that remind a user to perform other necessary configurations once the country has been imported. See the file structure reference linked above for an example.

When changes to the installation procedure occur and store owners grab the latest version of the file, there must be a way for them to make the changes without having to first uninstall the old file. Hence the use of update functions. These take a single argument $version. The body of the function should then be governed a switch on the value of this variable. In the case of each version you should include code that makes the necessary alterations or additions to get the database schema or variables updated to the current version.

For example, if I realized I had forgotten to set a variable in the initial release of the U.S. import file, I would need to rename the file to united_states_223_2.cif and add the following function:

<?php
function united_states_update($version) {
  switch (
$version) {
    case
2:
     
variable_set('forgotten_variable', 7);
      break;
  }
}
?>

The uninstall function is simply there to take care of any extra settings you have added. Ãœbercart will itself remove rows from the tables uc_countries and uc_zones and delete the address format variable, but you must undo any other additions you have made. (Really, I don't imagine anyone needs to worry about this yet.) The uninstall function does not need any arguments.

Please note that that install function should be kept up to date while the update function merely exists to move previous versions of a country to the most recent. If multiple updates are necessary, the update function will be called for every version between the current version and the latest version available.

Things to put in import files:

A brief overview of things to include in import files was given above. Please review this list, make sure your import file is comprehensive for your country.

1. Add the appropriate row to the table uc_countries using db_query(). This includes the country ID, country name, two digit code, three digit code, and most recent version number.

<?php
  db_query
("INSERT INTO {uc_countries} VALUES ('840', 'United States', 'US', 'USA', 1)");
?>

2. Add the appropriate rows to the table uc_zones using db_query(). Zones are geographical areas like states and provinces. These rows should use %d in conjunction with uc_get_zone_ids($num) for the zone's ID, the country ID the zone is in, the zone's abbreviation, and the zone's name. uc_get_zone_ids($num) takes a numeric argument being the number of zones you're inserting and returns an array of values that will map to the %d's in your query. This is the standard printf syntax used by db_query().

<?php
  db_query
("INSERT INTO {uc_zones} VALUES (%d, 840, 'KY', 'Kentucky')", uc_get_zone_ids(1));
?>

3. Call uc_set_address_format($country_id, $format) to set the address format for your country. Please review the address format instructions in the user guide for more information. If none is set, Ãœbercart will default to the address format of the U.S. The first argument should be the country ID, the second should be the format string. Use double quotes for the format string so \r\n can be escaped into <br> for display purposes.

<?php
  uc_set_address_format
(840, "!company\r\n!first_name !last_name\r\n!street1\r\n!street2\r\n!city, !zone_code !postal_code\r\n!country_name_if");
?>

4. Add any other variables or make any other function calls needed for your country's support. This will be fleshed out later, but we imagine things like adding conditions to tax rules or some other country specific support for core systems. We may just relegate these to modules, though.

The final word:

So, go ahead and get your country files going. If a thread does not exist for your country in the Internationalization forum, please create one according to these guidelines. Post the country file for review in your thread. If a thread already exists and you aren't the creator, reply to the thread and post the file in your reply for review. If you are the creator, please edit your original post and attach the latest country import file to it. As country import files are created and approved, they will be added to the core Ãœbercart packages.