Net_GeoIP

What is GeoIP?

Here GeoIP refers to a specific geolocation product from Maxmind LLC (http://www.maxmind.com). Maxmind makes free and commercial databases that map IP addresses to geographic location. The free version of the database only contains country information, while the commercial versions can return information including city, postal code, telephone area code, ISP, owning organization, etc.

These databases have many (probably obvious) applications in modern web applications -- from suggesting local mirrors, to advanced network statistics, to credit card fraud prevention, etc.

There are a couple other free packages [that I know of] that provide IP-to-Country mapping databases.

• http://weirdsilence.net/ip2c.php
• http://ip-to-country.webhosting.info/

I don't know about differences in how these databases are generated, their accuracy, or how currenty they are. While IP-to-Country is the only free GeoIP database from Maxmind, it is also represents a small portion of what GeoIP can do. GeoIP includes databases to that can map IP addresses down to the postal code or telephone area code level and report on owning organization and the ISP that uses the address.

What is this Library?

This library is a port and redesign of the Maxmind PHP API to PHP5 and PEAR standards. The API is actually modeled on the Java API (as the Maxmind PHP API is largely procedural) but uses the binary parsing code from the original PHP version.

This library supports all of the Maxmind databases in binary format:

• Country
• Region (REV0 and REV1)
• City (REV0 and REV1)
• Organization
• ISP

This class also supports memory caching (within a single script load) and shared memory (shmop) storage of the database.

Net_GeoIP does not require any network connectivity in order to perform the geolocation lookups.

This class does not depend on any other PEAR packages.

Why PHP5?

Because PHP5 is the new version of PHP. This classes uses excpetions for error handling, static properties, PPP, and other "syntactic sugar" like class constants provided by the new PHP5 OO model.

Since initial proposal, I have learned that PHP5 software in PEAR does not have very strong support. This package will remain in a non-stable state until PHP5 has reached a stable level. While no official requirement or guideline has been published, I would feel comfortable releasing a stable version on or after the release of PHP 5.0.1.

Many may not be able to make use of this package because of the PHP5 requirement. That's unfortunate. For those people stuck with PHP4 for whatever reason, I would direct your attention to the Horde I18_GeoIP package which provides the ip-to-country portion of this package. If you need support for the bigger databases, then use the official Maxmind [procedural] PHP API.

Exceptions

Because this class uses PHP5, it does not return PEAR_Error or use stack-based error handling (ErrorStack); instead, it throws Exception objects any place a PHP4 PEAR class would have returned a PEAR_Error object. The exceptions are documented in the methods that throw them and it is the developer's job to catch them, or otherwise handle them using set_exception_handler().

I plan to have this class throw PEAR_Exception when that is available (i.e. included in PHP distribution). Of course a change to throw PEAR_Exception will not break backwards compatibility since PEAR_Exception instanceof Exception.

How to Use

Obtaining a Database

You must first download and decompress a database. You can get a free country database from http://www.maxmind.com/app/geoip_country .

Instantiate the Class

Once you have a database, instantiate the class passing in the location to the database you wish to use.
<php>
$geoip = Net_GeoIP::getInstance('/path/to/GeoIP.dat', Net_GeoIP::SHARED_MEMORY);
</php>

Perform the Lookup Query

The API you use for queries depends on the database you have.

Free Country Database

Most people will probably be using the free database, which will only perform country name or country code lookups.
<php>
$country_name = $geoip->lookupCountryName($_SERVER['REMOTE_ADDR']);
$country_code = $geoip->lookupCountryCode($_SERVER['REMOTE_ADDR']);
</php>

Region Database

The region database includes region (e.g. US state, Canadian province) info in addition to country.
<php>
// for [non-free] region db:
list($ctry_code, $region) = $geoip->lookupRegion($_SERVER['REMOTE_ADDR']);
</php>

City Database

The city database populates a Net_GeoIP_Location object, which contains the most complete set of data.
<php>
$location = $geoip->lookupLocation($_SERVER['REMOTE_ADDR']);
print "city: " . $location->city . ", " . $location->region;
print "lat: " . $location->latitude . ", long: " . $location->longitude;
</php>

Org or ISP Database

The organization and ISP databases are separate databases, but use the same API to return information.
<php>
$org_or_isp_name = $geoip->lookupOrg($_SERVER['REMOTE_ADDR']);
</php>

Related Software

In PEAR

The only other similar package that I'm aware of in PEAR is the Net_Geo package. The main difference is that Net_Geo performs lookups using a CAIDA public www site (as far as I can tell) and does not support the level of detail possible with Maxmind's [commercial] databases.

To address the issues of integration, I do not feel that this package is a driver for a more general IP2Country package, because it provides a good deal more than that (most of the code in this library focuses on the higher levels of detail). I do feel that Net_Geo is probably a good starting point for a generic library since it provides simply ip-to-country lookups (AFAIK); one of the drivers in fact could be a GeoIP driver that uses Net_GeoIP.

Elsewhere

Horde has a PHP4 version of the GeoIP package, which is now also available under the terms of the LGPL (due to Maxmind licensing change). The Horde version provides support for the free country database only. http://cvs.sourceforge.net/viewcvs.py/*checkout*/geoip/php/geoip.inc?content-type=text%2Fplain&rev=1.16

(The Horde version would be a good candidate for the GeoIP driver for Net_Geo or for a more specifically names IP2C package.)
darknet markets