Net_GeoIP
[ class tree: Net_GeoIP ] [ index: Net_GeoIP ] [ all elements ]

Class: Net_GeoIP

Source Location: /Net_GeoIP-1.0.0/Net/GeoIP.php

Class Overview


GeoIP class provides an API for performing geo-location lookups based on IP address.


Author(s):

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 136]
GeoIP class provides an API for performing geo-location lookups based on IP address.

To use this class you must have a [binary version] GeoIP database. There is a free GeoIP country database which can be obtained from Maxmind: http://www.maxmind.com/app/geoip_country

SIMPLE USE

Create an instance:

  1.  $geoip Net_GeoIP::getInstance('/path/to/geoipdb.dat'Net_GeoIP::SHARED_MEMORY);

Depending on which database you are using (free, or one of paid versions) you must use appropriate lookup method:

  1.  // for free country db:
  2.  $country_name $geoip->lookupCountryName($_SERVER['REMOTE_ADDR']);
  3.  $country_code $geoip->lookupCountryCode($_SERVER['REMOTE_ADDR']);
  4.  
  5.  // for [non-free] region db:
  6.  list($ctry_code$region$geoip->lookupRegion($_SERVER['REMOTE_ADDR']);
  7.  
  8.  // for [non-free] city db:
  9.  $location $geoip->lookupLocation($_SERVER['REMOTE_ADDR']);
  10.  print "city: " $location->city . ", " $location->region;
  11.  print "lat: " $location->latitude . ", long: " $location->longitude;
  12.  
  13.  // for organization or ISP db:
  14.  $org_or_isp_name $geoip->lookupOrg($_SERVER['REMOTE_ADDR']);

MULTIPLE INSTANCES

You can have several instances of this class, one for each database file you are using. You should use the static getInstance() singleton method to save on overhead of setting up database segments. Note that only one instance is stored per filename, and any flags will be ignored if an instance already exists for the specifiedfilename.

Special note on using SHARED_MEMORY flag

If you are using SHARED_MEMORY (shmop) you can only use SHARED_MEMORY for one (1) instance (i.e. for one database). Any subsequent attempts to instantiate using SHARED_MEMORY will read the same shared memory block already initialized, and therefore will cause problems since the expected database format won't match the database in the shared memory block.

Note that there is no easy way to flag "nice errors" to prevent attempts to create new instances using SHARED_MEMORY flag and it is also not posible (in a safe way) to allow new instances to overwrite the shared memory block.

In short, is you are using multiple databses, use the SHARED_MEMORY flag with care.

LOOKUPS ON HOSTNAMES

Note that this PHP API does NOT support lookups on hostnames. This is so that the public API can be kept simple and so that the lookup functions don't need to try name lookups if IP lookup fails (which would be the only way to keep the API simple and support name-based lookups).

If you do not know the IP address, you can convert an name to IP very simply using PHP native functions or other libraries:

  1.      $geoip->lookupCountryName(gethostbyname('www.sunset.se'));

Or, if you don't know whether an address is a name or ip address, use application-level logic:

  1.  if (ip2long($ip_or_name=== false{
  2.    $ip gethostbyname($ip_or_name);
  3.  else {
  4.    $ip $ip_or_name;
  5.  }
  6.  $ctry $geoip->lookupCountryName($ip);



[ Top ]


Class Variables

$COUNTRY_CODES = array(
      "", "AP", "EU", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AN", "AO", "AQ",
      "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH",
      "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA",
      "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU",
      "CV", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG",
      "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "FX", "GA", "GB",
      "GD", "GE", "GF", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT",
      "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN",
      "IO", "IQ", "IR", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM",
      "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS",
      "LT", "LU", "LV", "LY", "MA", "MC", "MD", "MG", "MH", "MK", "ML", "MM", "MN",
      "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA",
      "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA",
      "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY",
      "QA", "RE", "RO", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI",
      "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "ST", "SV", "SY", "SZ", "TC", "TD",
      "TF", "TG", "TH", "TJ", "TK", "TM", "TN", "TO", "TL", "TR", "TT", "TV", "TW",
      "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN",
      "VU", "WF", "WS", "YE", "YT", "RS", "ZA", "ZM", "ME", "ZW", "A1", "A2", "O1",
      "AX", "GG", "IM", "JE", "BL", "MF"
        )

[line 148]

  • Access: public

Type:   mixed


[ Top ]

$COUNTRY_CODES3 = array(
    "","AP","EU","AND","ARE","AFG","ATG","AIA","ALB","ARM","ANT","AGO","AQ","ARG",
    "ASM","AUT","AUS","ABW","AZE","BIH","BRB","BGD","BEL","BFA","BGR","BHR","BDI",
    "BEN","BMU","BRN","BOL","BRA","BHS","BTN","BV","BWA","BLR","BLZ","CAN","CC",
    "COD","CAF","COG","CHE","CIV","COK","CHL","CMR","CHN","COL","CRI","CUB","CPV",
    "CX","CYP","CZE","DEU","DJI","DNK","DMA","DOM","DZA","ECU","EST","EGY","ESH",
    "ERI","ESP","ETH","FIN","FJI","FLK","FSM","FRO","FRA","FX","GAB","GBR","GRD",
    "GEO","GUF","GHA","GIB","GRL","GMB","GIN","GLP","GNQ","GRC","GS","GTM","GUM",
    "GNB","GUY","HKG","HM","HND","HRV","HTI","HUN","IDN","IRL","ISR","IND","IO",
    "IRQ","IRN","ISL","ITA","JAM","JOR","JPN","KEN","KGZ","KHM","KIR","COM","KNA",
    "PRK","KOR","KWT","CYM","KAZ","LAO","LBN","LCA","LIE","LKA","LBR","LSO","LTU",
    "LUX","LVA","LBY","MAR","MCO","MDA","MDG","MHL","MKD","MLI","MMR","MNG","MAC",
    "MNP","MTQ","MRT","MSR","MLT","MUS","MDV","MWI","MEX","MYS","MOZ","NAM","NCL",
    "NER","NFK","NGA","NIC","NLD","NOR","NPL","NRU","NIU","NZL","OMN","PAN","PER",
    "PYF","PNG","PHL","PAK","POL","SPM","PCN","PRI","PSE","PRT","PLW","PRY","QAT",
    "REU","ROU","RUS","RWA","SAU","SLB","SYC","SDN","SWE","SGP","SHN","SVN","SJM",
    "SVK","SLE","SMR","SEN","SOM","SUR","STP","SLV","SYR","SWZ","TCA","TCD","TF",
    "TGO","THA","TJK","TKL","TLS","TKM","TUN","TON","TUR","TTO","TUV","TWN","TZA",
    "UKR","UGA","UM","USA","URY","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT",
    "WLF","WSM","YEM","YT","SRB","ZAF","ZMB","MNE","ZWE","A1","A2","O1",
    "ALA","GGY","IMN","JEY","BLM","MAF"
        )

[line 171]

  • Access: public

Type:   mixed


[ Top ]

$COUNTRY_NAMES = array(
        "", "Asia/Pacific Region", "Europe", "Andorra", "United Arab Emirates",
        "Afghanistan", "Antigua and Barbuda", "Anguilla", "Albania", "Armenia",
        "Netherlands Antilles", "Angola", "Antarctica", "Argentina", "American Samoa",
        "Austria", "Australia", "Aruba", "Azerbaijan", "Bosnia and Herzegovina",
        "Barbados", "Bangladesh", "Belgium", "Burkina Faso", "Bulgaria", "Bahrain",
        "Burundi", "Benin", "Bermuda", "Brunei Darussalam", "Bolivia", "Brazil",
        "Bahamas", "Bhutan", "Bouvet Island", "Botswana", "Belarus", "Belize",
        "Canada", "Cocos (Keeling) Islands", "Congo, The Democratic Republic of the",
        "Central African Republic", "Congo", "Switzerland", "Cote D'Ivoire", "Cook Islands",
        "Chile", "Cameroon", "China", "Colombia", "Costa Rica", "Cuba", "Cape Verde",
        "Christmas Island", "Cyprus", "Czech Republic", "Germany", "Djibouti",
        "Denmark", "Dominica", "Dominican Republic", "Algeria", "Ecuador", "Estonia",
        "Egypt", "Western Sahara", "Eritrea", "Spain", "Ethiopia", "Finland", "Fiji",
        "Falkland Islands (Malvinas)", "Micronesia, Federated States of", "Faroe Islands",
        "France", "France, Metropolitan", "Gabon", "United Kingdom",
        "Grenada", "Georgia", "French Guiana", "Ghana", "Gibraltar", "Greenland",
        "Gambia", "Guinea", "Guadeloupe", "Equatorial Guinea", "Greece", "South Georgia and the South Sandwich Islands",
        "Guatemala", "Guam", "Guinea-Bissau",
        "Guyana", "Hong Kong", "Heard Island and McDonald Islands", "Honduras",
        "Croatia", "Haiti", "Hungary", "Indonesia", "Ireland", "Israel", "India",
        "British Indian Ocean Territory", "Iraq", "Iran, Islamic Republic of",
        "Iceland", "Italy", "Jamaica", "Jordan", "Japan", "Kenya", "Kyrgyzstan",
        "Cambodia", "Kiribati", "Comoros", "Saint Kitts and Nevis", "Korea, Democratic People's Republic of",
        "Korea, Republic of", "Kuwait", "Cayman Islands",
        "Kazakstan", "Lao People's Democratic Republic", "Lebanon", "Saint Lucia",
        "Liechtenstein", "Sri Lanka", "Liberia", "Lesotho", "Lithuania", "Luxembourg",
        "Latvia", "Libyan Arab Jamahiriya", "Morocco", "Monaco", "Moldova, Republic of",
        "Madagascar", "Marshall Islands", "Macedonia",
        "Mali", "Myanmar", "Mongolia", "Macau", "Northern Mariana Islands",
        "Martinique", "Mauritania", "Montserrat", "Malta", "Mauritius", "Maldives",
        "Malawi", "Mexico", "Malaysia", "Mozambique", "Namibia", "New Caledonia",
        "Niger", "Norfolk Island", "Nigeria", "Nicaragua", "Netherlands", "Norway",
        "Nepal", "Nauru", "Niue", "New Zealand", "Oman", "Panama", "Peru", "French Polynesia",
        "Papua New Guinea", "Philippines", "Pakistan", "Poland", "Saint Pierre and Miquelon",
        "Pitcairn Islands", "Puerto Rico", "Palestinian Territory",
        "Portugal", "Palau", "Paraguay", "Qatar", "Reunion", "Romania",
        "Russian Federation", "Rwanda", "Saudi Arabia", "Solomon Islands",
        "Seychelles", "Sudan", "Sweden", "Singapore", "Saint Helena", "Slovenia",
        "Svalbard and Jan Mayen", "Slovakia", "Sierra Leone", "San Marino", "Senegal",
        "Somalia", "Suriname", "Sao Tome and Principe", "El Salvador", "Syrian Arab Republic",
        "Swaziland", "Turks and Caicos Islands", "Chad", "French Southern Territories",
        "Togo", "Thailand", "Tajikistan", "Tokelau", "Turkmenistan",
        "Tunisia", "Tonga", "Timor-Leste", "Turkey", "Trinidad and Tobago", "Tuvalu",
        "Taiwan", "Tanzania, United Republic of", "Ukraine",
        "Uganda", "United States Minor Outlying Islands", "United States", "Uruguay",
        "Uzbekistan", "Holy See (Vatican City State)", "Saint Vincent and the Grenadines",
        "Venezuela", "Virgin Islands, British", "Virgin Islands, U.S.",
        "Vietnam", "Vanuatu", "Wallis and Futuna", "Samoa", "Yemen", "Mayotte",
        "Serbia", "South Africa", "Zambia", "Montenegro", "Zimbabwe",
        "Anonymous Proxy","Satellite Provider","Other",
        "Aland Islands","Guernsey","Isle of Man","Jersey","Saint Barthelemy","Saint Martin"
        )

[line 194]

  • Access: public

Type:   mixed


[ Top ]



Method Detail

__construct (Constructor)   [line 333]

Net_GeoIP __construct( [string $filename = null], [int $flags = null])

Construct a Net_GeoIP instance.

You should use the getInstance() method if you plan to use multiple databases or the same database from several different places in your script.


Parameters:

string   $filename     Path to binary geoip database.
int   $flags     Flags

[ Top ]

close   [line 561]

int close( )

Closes the geoip database.
  • Return: Status of close command.
  • Access: public

[ Top ]

getInstance   [line 392]

Net_GeoIP getInstance( [string $filename = null], [int $flags = null])

Singleton method, use this to get an instance and avoid re-parsing the db.

Unique instances are instantiated based on the filename of the db. The flags are ignored -- in that requests to for instance with same filename but different flags will return the already-instantiated instance. For example:

  1.  // create new instance with memory_cache enabled
  2.  $geoip Net_GeoIP::getInstance('C:\mydb.dat'Net_GeoIP::MEMORY_CACHE);
  3.  ....
  4.  
  5.  // later in code, request instance with no flags specified.
  6.  $geoip Net_GeoIP::getInstance('C:\mydb.dat');
  7.  
  8.  // Normally this means no MEMORY_CACHE but since an instance
  9.  // with memory cache enabled has already been created for 'C:\mydb.dat', the
  10.  // existing instance (with memory cache) will be returned.

NOTE: You can only use SHARED_MEMORY flag for one instance! Any subsquent instances that attempt to use the SHARED_MEMORY will use the *same* shared memory, which will break your script.

  • Access: public

Parameters:

string   $filename     Filename
int   $flags     Flags that control class behavior.
  • Net_GeoIp::SHARED_MEMORY Use SHMOP to share a db among multiple PHP instances. NOTE: ONLY ONE GEOIP INSTANCE CAN USE SHARED MEMORY!!!
  • Net_GeoIp::MEMORY_CACHE Store the full contents of the database in memory for current script. This is useful if you access the database several times in a script.
  • Net_GeoIp::STANDARD [default] standard no-cache version.

[ Top ]

getOrg   [line 748]

string getOrg( int $ipnum)

Seek and return organization (or ISP) name for converted IP addr.
  • Return: The organization
  • Access: protected

Parameters:

int   $ipnum     Converted IP address.

[ Top ]

getRecord   [line 812]

Net_GeoIP_Location getRecord( int $ipnum)

Seek and populate Net_GeoIP_Location object for converted IP addr.

Note: this

  • Access: protected

Parameters:

int   $ipnum     Converted IP address.

[ Top ]

getRegion   [line 772]

array getRegion( int $ipnum)

Seek and return the region info (array containing country code and region name) for converted IP addr.
  • Return: Array containing country code and region: array($country_code, $region)
  • Access: protected

Parameters:

int   $ipnum     Converted IP address.

[ Top ]

loadSharedMemory   [line 446]

void loadSharedMemory( string $filename)

Loads the database file into shared memory.
  • Throws: PEAR_Exception - if unable to read the db file.
  • Access: protected

Parameters:

string   $filename     Path to database file to read into shared memory.

[ Top ]

lookupCountryCode   [line 609]

string lookupCountryCode( string $addr)

Returns 2-letter country code (e.g. 'CA') for specified IP address.

Use this method if you have a Country database.


Parameters:

string   $addr     IP address (hostname not allowed).

[ Top ]

lookupCountryId   [line 586]

string lookupCountryId( string $addr)

Get the country index.

This method is called by the lookupCountryCode() and lookupCountryName() methods. It lookups up the index ('id') for the country which is the key for the code and name.

  • Return: ID for the country
  • Throws: PEAR_Exception - if IP address is invalid.
    • if database type is incorrect
  • Access: protected

Parameters:

string   $addr     IP address (hostname not allowed)

[ Top ]

lookupCountryName   [line 624]

string lookupCountryName( string $addr)

Returns full country name for specified IP address.

Use this method if you have a Country database.


Parameters:

string   $addr     IP address (hostname not allowed).

[ Top ]

lookupLocation   [line 728]

Net_GeoIP_Location lookupLocation( string $addr)

Lookup the location record for given IP address.

Use this method if you have a City database.

  • Return: The full location record.
  • Throws: PEAR_Exception - if IP address is invalid.
  • Access: public

Parameters:

string   $addr     IP address (hostname not allowed).

[ Top ]

lookupOrg   [line 684]

string lookupOrg( string $addr)

Lookup the organization (or ISP) for given IP address.

Use this method if you have an Organization/ISP database.

  • Return: The organization
  • Throws: PEAR_Exception - if IP address is invalid.
    • if database is of wrong type
  • Access: public

Parameters:

string   $addr     IP address (hostname not allowed).

[ Top ]

lookupRegion   [line 706]

array lookupRegion( string $addr)

Lookup the region for given IP address.

Use this method if you have a Region database.

  • Return: Array containing country code and region: array($country_code, $region)
  • Throws: PEAR_Exception - if IP address is invalid.
  • Access: public

Parameters:

string   $addr     IP address (hostname not allowed).

[ Top ]

open   [line 410]

void open( string $filename, [int $flags = null])

Opens geoip database at filename and with specified flags.
  • Throws: PEAR_Exception if unable to open specified file or shared memory.
  • Access: public

Parameters:

string   $filename     File to open
int   $flags     Flags

[ Top ]

seekCountry   [line 638]

int seekCountry( int $ipnum)

Using the record length and appropriate start points, seek to the country that corresponds to the converted IP address integer.
  • Return: Offset of start of record.
  • Throws: PEAR_Exception - if fseek() fails on the file or no results after traversing the database (indicating corrupt db).
  • Access: protected

Parameters:

int   $ipnum     Result of ip2long() conversion.

[ Top ]

setupSegments   [line 479]

void setupSegments( )

Parses the database file to determine what kind of database is being used and setup segment sizes and start points that will be used by the seek*() methods later.
  • Access: protected

[ Top ]


Documentation generated on Thu, 12 May 2011 12:30:04 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.