Cities of the World

Cities of the World is not a simple PHP class, but somewhat a handy tool package that could simplify the task of dealing with lists of countries, and their respective cities (states for the USA - stations for Antarctica) while coding web forms.

Package:
The package contains following files.

cities.csv, is the main data source in .csv format. It contains 6,940 rows with ' ; ' as field and ' \r\n ' characters as line delimiter.
cities_sql.php, is the script to create a MySQL database and import the content of cities.csv into it.
class_cities.inc, is the Class handling the creation and population of dropdown SELECT lists of countries and their cities (states for the USA - stations for Antarctica) .
test.php, is a script demonstrating the usage of the class.
readme.html, this very file.
license.txt, a copy of GNU GENERAL PUBLIC LICENSE.

Requirements:
PHP 4.x.x and above, MySQL.

Compatibility:
Cities of the World was tested under
[RedHat-7.3 + Apache-1.3.26. + PHP-4.3.1 + MySQL-3.23.52] and
[Windows-XP Pro. + Apache-1.3.24 + PHP-4.3.0 + MySQL-3.23.49]

Description:
To be able to use the provided class, you should first store the appropriate data into your database. Two files, cities.csv and cities_sql.php are intended for this step.
Once the data is available, through class_cities.inc you may create a Country dropdown list with 232 countries and, a City dropdown populated with the cities (states for the USA - stations for Antarctica) of a preselected country. An embedded JavaScript disables the City dropdown if a country different than the one intended is selected.

Database Structure:
The database table will contain these five columns:
'unique_id'
an incremental integer from 1 to 6940, which can be used as unique_id for each row.
'local_id'
a country specific incremental integer from 1 to whatever the number of cities for each country.
'city'
the names of the cities.
'cc'
two letter country codes.
'country'
the names of the countries.
Available two letter country codes are as follows:

af -> Afghanistan
al -> Albania
dz -> Algeria
as -> American Samoa
ad -> Andorra
ao -> Angola
ai -> Anguilla
aq -> Antarctica
ag -> Antigua & Barbuda
ar -> Argentina
am -> Armenia
aw -> Aruba
au -> Australia
at -> Austria
az -> Azerbaijan
bs -> Bahamas
bh -> Bahrain
bd -> Bangladesh
bb -> Barbados
by -> Belarus
be -> Belgium
bz -> Belize
bj -> Benin
bm -> Bermuda
bt -> Bhutan
bo -> Bolivia
ba -> Bosnia-Herzegovina
bw -> Botswana
br -> Brazil
vg -> British Virgin Islands
bn -> Brunei
bg -> Bulgaria
bf -> Burkina Faso
bi -> Burundi
kh -> Cambodia
cm -> Cameroon
ca -> Canada
cv -> Cape Verde
ky -> Cayman Islands
cf -> Central Africa
td -> Chad
cl -> Chile
cn -> China
co -> Colombia
km -> Comoros
cg -> Congo
cd -> Congo (Dem. Rep.)
ck -> Cook Islands
cr -> Costa Rica
hr -> Croatia
cu -> Cuba
cy -> Cyprus
cz -> Czech Republic
dk -> Denmark
dj -> Djibouti
dm -> Dominica
do -> Dominican Republic
tp -> East Timor
ec -> Ecuador
eg -> Egypt
sv -> El Salvador
gq -> Equatorial Guinea
er -> Eritrea
ee -> Estonia
et -> Ethiopia
xa -> Ext. Territ. of Australia
fk -> Falkland Islands
fo -> Faroe Islands
fj -> Fiji
fi -> Finland
fr -> France
gf -> French Guiana
pf -> French Polynesia
ga -> Gabon
gm -> Gambia
ge -> Georgia
de -> Germany
gh -> Ghana
gi -> Gibraltar
gr -> Greece
gl -> Greenland
gd -> Grenada
gp -> Guadeloupe
gu -> Guam
gt -> Guatemala
xu -> Guernsey and Alderney
gn -> Guinea
gw -> Guinea Bissau
gy -> Guyana
ht -> Haiti
hn -> Honduras
hu -> Hungary
is -> Iceland
in -> India
id -> Indonesia
ir -> Iran
iq -> Iraq
ie -> Ireland
il -> Israel
it -> Italy
ci -> Ivory Coast
jm -> Jamaica
jp -> Japan
xj -> Jersey
jo -> Jordan
kz -> Kazakhstan
ke -> Kenya
ki -> Kiribati
kp -> Korea (North)
kr -> Korea (South)
kw -> Kuwait
kg -> Kyrgyzstan
la -> Laos
lv -> Latvia
lb -> Lebanon
ls -> Lesotho
lr -> Liberia
ly -> Libya
li -> Liechtenstein
lt -> Lithuania
lu -> Luxembourg
mk -> Macedonia
mg -> Madagascar
mw -> Malawi
my -> Malaysia
mv -> Maldives
ml -> Mali
mt -> Malta
xm -> Man (Isle of)
mh -> Marshall Islands
mq -> Martinique
mr -> Mauritania
mu -> Mauritius
yt -> Mayotte
mx -> Mexico
fm -> Micronesia
md -> Moldova
mc -> Monaco
mn -> Mongolia
ma -> Morocco
mz -> Mozambique
mm -> Myanmar
na -> Namibia
nr -> Nauru
np -> Nepal
nl -> Netherlands
an -> Netherlands Antilles
nc -> New Caledonia
nz -> New Zealand
ni -> Nicaragua
ne -> Niger
ng -> Nigeria
nu -> Niue
nf -> Norfolk
mp -> Northern Mariana Islands
om -> Oman
pk -> Pakistan
pw -> Palau
ps -> Palestine
pa -> Panama
pg -> Papua New Guinea
py -> Paraguay
pe -> Peru
ph -> Philippines
pl -> Poland
pt -> Portugal
pr -> Puerto Rico
qa -> Qatar
re -> Réunion
ro -> Romania
ru -> Russia
rw -> Rwanda
eh -> Sahara
sh -> Saint Helena
kn -> Saint Kitts and Nevis
lc -> Saint Lucia
pm -> Saint Pierre & Miquelon
vc -> St. Vincent & the Grenadines
ws -> Samoa
sm -> San Marino
st -> São Tomé and Príncipe
sa -> Saudi Arabia
sn -> Senegal
yu -> Serbia and Montenegro
sc -> Seychelles
sl -> Sierra Leone
sg -> Singapore
sk -> Slovakia
si -> Slovenia
xg -> Smaller Territories of the UK
sb -> Solomon Islands
so -> Somalia
za -> South Africa
es -> Spain
lk -> Sri Lanka
sd -> Sudan
sr -> Suriname
sj -> Svalbard and Jan Mayen
sz -> Swaziland
se -> Sweden
ch -> Switzerland
sy -> Syria
tw -> Taiwan
tj -> Tajikistan
tz -> Tanzania
tf -> Terres Australes
th -> Thailand
tg -> Togo
tk -> Tokelau
to -> Tonga
tt -> Trinidad and Tobago
tn -> Tunisia
tr -> Turkey
tm -> Turkmenistan
tc -> Turks and Caicos Islands
tv -> Tuvalu
ug -> Uganda
ua -> Ukraine
ae -> United Arab Emirates
gb -> United Kingdom
us -> United States of America
uy -> Uruguay
uz -> Uzbekistan
vu -> Vanuatu
va -> Vatican
ve -> Venezuela
vn -> Vietnam
vi -> Virgin Islands of the USA
wf -> Wallis & Futuna
ye -> Yemen
zm -> Zambia
zw -> Zimbabwe

Creating the Database:
Unzip the package in the directory of your choice.
Open cities_sql.php and edit these 6 variables:
$db_host = "";   // This is the name of your db_host. In most cases "localhost" would be OK.
$db_user = "";   // This is the user name necessary to connect to database server. You need to have CREATE and FILE privileges granted to this name.
$db_pass = "";   // This is the password necessary to connect to database server.
$csv_file_path = "";   // This is the absolute physical path to the 'cities.csv' file. Within the 'cities_sql.php' file you will find this variable twice, both commented (having // at the beginning) and illustrating how in Windows and Unix/Linux systems, a value should be assigned. Uncomment (delete // at the beginning) one of them and edit it the way it fits your needs.
$db_name = "";   // This is the name of the database that will hold your data.
$db_table = "";   // This is the name of the table where the data will be stored in.

IMPORTANT: If you want to create a new database to hold this data, leave the rest of cities_sql.php as it is. If you want to append a new table to an already existing database comment  (add // at the beginning)  these two lines:

line 53:   $query = mysql_query($create_db);
line 54:   if (mysql_error()) echo("failure to create the db [".$db_name."] => ".mysql_error()."<br>");

Once you are over with the editing, save your work and upload both cities_sql.php and cities.csv to your server. On Unix/Linux chmod cities.csv 0666. Put cities_sql.php somewhere within your web area and call it from your browser.

Usage:

<php
// Change these variables to whatever you have used in 'cities_sql.php' file.
$db_host = "localhost";
$db_user = "";
$db_pass = "";
$db_name = "countries_cities";
$db_table = "cities";
$country = ""; // two letter country_code of the country for which the cities will be shown.

/* require(), instead of include() to abort execution if the class is not found */
require("class_cities.inc");

/* create a new instance of the class */
$cities = new cities($db_host, $db_user, $db_pass, $db_name);
?>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Your Page Title</title>
<!-- embed JavaScript to control whether the second dropdown list will be enabled/disabled -->
<? echo $cities –> java_script($country) ?>
</head>
<body>
......
<tr>
    <td>Country:</td>
    <!-- create countries' dropdown list -->
    <td><? echo $cities –> country_list($db_table) ?></td>
</tr>
<tr>
    <!-- determine the field caption -->
    <td><? echo $cities –> caption($country) ?></td>
    <!-- create cities' dropdown list -->
    <td><? echo $cities –> city_list($db_table, $country) ?></td>
</tr>
......

Examples:

Output with Turkey as preselected country:     
$country = "tr";
Country:
City:   for Turkey
 
 
 
 
Output with USA as preselected country:     
$country = "us";
Country:
State:   for United States of America
 
 
 
 
Output with Antarctica as preselected country:     
$country = "aq";
Country:
Station:   for Antarctica
 

To Do:
Integration with some IP based localization system to determine the value of $country automaticly for a complete hands off solution..

Enjoy...

A. M. OKAR