Home » Networking » Net_GeoIP » Manual

Net_GeoIP::getInstance()

Net_GeoIP::getInstance() – method to get an instance and avoid re-parsing the database

Synopsis

object getInstance() ( string $filename [, int $flags] )

Description

This method is an implementation of the so-called singleton pattern and is the preferred way to create instances of Net_GeoIP.

Creating an instance of Net_GeoIP

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat", Net_GeoIP::SHARED_MEMORY);
?>

Multiple Instances

If you want to use multiple databases in one application, you will need to create an instance of Net_GeoIP for each database. Using the singleton getInstance() method will make sure that at any given point exactly one object for each database exists, which saves on overhead of setting up database segments.

Parameter

• string $filename - Name of (and path to) the database file
• int $flags - Flags that control the class behaviour. This parameter can be one of the following class constants:
  • Net_GeoIp::SHARED_MEMORY - use SHMOP to share a database among multiple PHP instances.

    Only one Net_GeoIP instance can use shared memory at a time.

    If you are using Net_GeoIP::SHARED_MEMORY (shmop) you can only use Net_GeoIP::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 Net_GeoIP::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 databases, use the Net_GeoIP::SHARED_MEMORY flag with care.

  • 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 - standard no-cache version. This is also the default value if this parameter is ommitted.

Net_GeoIP::lookupCountryName()

Net_GeoIP::lookupCountryName() – returns full country name for specified IP address

Synopsis

string lookupCountryName() ( string $addr )

Description

This method returns the full country name for the given IP address. It works with both the free and the non-free databases.

Looking up the country name

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupCountryName($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

• string $addr - IP address

  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:

  <?php
  $geoip->lookupCountryName(gethostbyname("example.com"));
  ?>

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

  <?php
  if (ip2long($ip_or_name) === false) {
      $ip = gethostbyname($ip_or_name);
  } else {
      $ip = $ip_or_name;
  }
  
  $country = $geoip->lookupCountryName($ip);
  ?>

Throws

This method sthrow an exception if the IP address is invalid or if the database type is incorrect.

Net_GeoIP::lookupCountryCode()

Net_GeoIP::lookupCountryCode() – returns 2-letter country code (e.g. "CA") for specified IP address

Synopsis

string lookupCountryCode() ( string $addr )

Description

This method returns the 2-letter country code for the given IP address. It works with both the free and the non-free databases.

Looking up the country code

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupCountryCode($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

• string $addr - IP address

  Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid or if the database type is incorrect.

Net_GeoIP::lookupRegion()

Net_GeoIP::lookupRegion() – returns the region for given IP address.

Synopsis

array lookupRegion() ( string $addr )

Description

This method returns an array containing the country code and the region for the specified IP address. It works only with a non-free Region database.

Looking up the region

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    list($country_code, $region) = $geoip->lookupRegion($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

• string $addr - IP address

  Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid.

Net_GeoIP::lookupLocation()

Net_GeoIP::lookupLocation() – returns the location record for specified IP address

Synopsis

object lookupLocation() ( string $addr )

Description

This method returns an instance of Net_GeoIP_Location for the specified IP address. It works only with a non-free City database.

Looking up the location record

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    $location = $geoip->lookupLocation($_SERVER['REMOTE_ADDR']);

    var_dump($location);

    printf("City: %s, %s\nLatitude: %s, Longitude: %s\n",
           $location->city, $location->region,
           $location->latitude, $location->longitude);

} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

• string $addr - IP address

  Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid.

Net_GeoIP::lookupOrg()

Net_GeoIP::lookupOrg() – returns the name of the organization or ISP for the given IP address.

Synopsis

string lookupOrg() ( string $addr )

Description

This method returns the name of the organization or of the ISP which has registered the IP address range that contains the specified IP address. It works only with a non-free Organization/ISP database.

Looking up organization name

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupOrg($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

• string $addr - IP address

  Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid or the database type is wrong.