geoip_functions.php

Summary

geoip_functions.php
Description	This file holds all extended functions which belongs to IP and GEOIP handling.
Examples
How to use the GeoIP-module for your own projects	See README.txt for original docu and geoip.inc for functions.
GeoIP-Functions
geoip_open_db	Opens GeoIP-database for use.
GEOIP_DATABASE_LOADED	The Constant GEOIP_DATABASE_LOADED will be defined when the GeoIP was opened successfully.
geoip_close_db	Closes GeoIP-database after use.
geoip_flag_html	Returns a piece of HTML-code to display a flag.
geoip_flag_link	Returns an absolute URL to a flag-image.
geoip_best_ip	Fetches best matching IP for actual connection.
geoip_list_ip	Fetches user-ip and proxy-ip if available.
geoip_fetch_hostname	Fetches hostname for given IP.
geoip_list_hostname	Fetches and checks hostname for a given IP.
geoip_is_proxy	Checks if the actual user ( $_SERVER['REMOTE_ADDR'] ) is behind a proxy.
geoip_in_bogons_list	Checks if the given IP is in an unallocated or private address range.
geoip_in_drop_list	Checks if the given IP is in spamhaus' drop-list.

Description

This file holds all extended functions which belongs to IP and GEOIP handling.

You have to include (require_once()) this file if you want to use the geoip-module.

Examples

Read the GeoIP-Database LICENSE.txt before using this module for your own projects, especially this part

 --- from LICENSE.txt ----
All advertising materials and documentation mentioning features or use of
this database must display the following acknowledgment:
"This product includes GeoLite data created by MaxMind,
available from http://maxmind.com/"
 -------------------------

How to use the GeoIP-module for your own projects

See README.txt for original docu and geoip.inc for functions. But do NOT use geoip_open()! Use geoip_open_db() instead!

If GeoIP-Module is required

// load geoip-functions
if(file_exists(WB_PATH.'/modules/geoip/geoip_functions.php'))
   require_once(WB_PATH.'/modules/geoip/geoip_functions.php');
else
   exit('GeoIP-module not installed!');

...

$gi = geoip_open_db(); // opens GeoIP database
if($gi===FALSE)
   exit(Failed to open GeoIP-database!);
$ip = geoip_best_ip();
echo 'You are from '.geoip_country_name_by_addr($gi, $ip);
geoip_close($gi);

If GeoIP-module is optional

// load geoip-functions, if available
if(file_exists(WB_PATH.'/modules/geoip/geoip_functions.php'))
   require_once(WB_PATH.'/modules/geoip/geoip_functions.php');

if(function_exists('geoip_open_db'))
   $gi = geoip_open_db(); // $gi will be FALSE if this fails
else
   $gi = FALSE;

// Now you can check against $gi or defined('GEOIP_DATABASE_LOADED')
// to see if geoip-database is ready to use
// if($gi) { // ready to use } else { // not available }
// if(defined('GEOIP_DATABASE_LOADED')) { // ready to use }
// else { // not available }

...

if($gi)
   $ip = geoip_best_ip();
else
   $ip = $_SERVER['REMOTE_ADDR'];

...

if($gi) {
   echo '<strong>You are from '.geoip_country_name_by_addr($gi, $ip).'</strong></br >';
} else {
   echo 'Your IP-Address is: '.$ip.'<br />';
}

if(defined('GEOIP_DATABASE_LOADED'))
   geoip_close($gi);

GeoIP-Functions

geoip_open_db

function geoip_open_db( $use_cache = FALSE )

Opens GeoIP-database for use.

Prototype

handle geoip_open_db( bool $use_cache )

Parameters

use_cache

(bool) Whether to cache the database in memory (TRUE), or not (FALSE).

Returns

A GeoIP Database-Handle.

In case of error, the function returns FALSE.

GEOIP_DATABASE_LOADED

The Constant GEOIP_DATABASE_LOADED will be defined when the GeoIP was opened successfully.

geoip_close_db

function geoip_close_db( $gi )

Closes GeoIP-database after use.

Prototype

void geoip_close_db( handle $gi )

Parameters

gi	(handle) The handle returned from geoip_open_db().

Returns

nothing.

geoip_flag_html

function geoip_flag_html( $gi,
$src )

Returns a piece of HTML-code to display a flag.

Prototype

string geoip_flag_html( handle $gi, string source )

Parameters

gi	(handle) The handle returned from geoip_open_db().
source	(string) An IP-Address (e.g. '100.20.101.90' ), or a Country-Code (e.g. 'DE' ), or a Country-Name (e.g. 'Germany' ).

Returns

A string, containing a piece of code to display an image from the supplied flags-collection.

For an unkown IP or Country-Name or -Code, the special (empty) __.png-flag will be returned.

Example

'<img class="geoip_worldflag" src="http://www.example.org/wb/modules/geoip/worldflags/de.png" alt="Germany" title="Germany" />'

geoip_flag_link

function geoip_flag_link( $gi,
$src )

Returns an absolute URL to a flag-image.

Prototype

string geoip_flag_html( handle $gi, string source )

Parameters

gi	(handle) The handle returned from geoip_open_db().
source	(string) An IP-Address (e.g. '100.20.101.90' ), or a Country-Code (e.g. 'DE' ), or a Country-Name (e.g. 'Germany' ).

Returns

A string, containing an absolute URL to an image from the supplied flags-collection.

For an unkown IP or Country-Name or -Code, a URL to the special (empty) __.png-flag will returned.

Example

'http://www.example.org/wb/modules/geoip/worldflags/'.$cc.'.png'

geoip_best_ip

function geoip_best_ip()

Fetches best matching IP for actual connection.

Prototype

string geoip_best_ip( void )

Parameters

Uses

$_SERVER['REMOTE_ADDR'];

Returns

A string with the fetched IP.

The returned IP is either the User-IP, or, if the user is hidden behind a proxy, that Proxy-IP.

There is no guarantee that the fetched ip is really "real"; users may forge it. But this is better than nothing

geoip_list_ip

function geoip_list_ip()

Fetches user-ip and proxy-ip if available.

Prototype

array geoip_list_ip( void )

Parameters

Uses

$_SERVER['REMOTE_ADDR'];

Returns

An array with User-IP and Proxy-IP (array(0=>'100.10.20.3', 1=>'200.20.10.20') ). User-IP or Proxy-IP may be FALSE

There is no guarantee that the fetched ip is really "real"; users may forge it. But this is better than nothing

Example

list($real_ip, $proxy_ip) = geoip_list_ip($_SERVER['REMOTE_ADDR']);

$real_ip │ $proxy_ip │ meaning
─────────┼───────────┼──────────────────────────────
100.1.2.3│   FALSE   │ real ip, no proxy ip
 FALSE   │ 200.1.2.3 │ real ip unknown, proxy ip
100.1.2.3│ 200.3.2.1 │ real ip, proxy ip

geoip_fetch_hostname

function geoip_fetch_hostname( $ip )

Fetches hostname for given IP.

Prototype

string geoip_open_db( string $ip )

Parameters

ip	(string) An IP-Address (e.g. '100.10.20.2' ).

Returns

The resolved Hostname, or the given IP if it isn't resolvable.

geoip_list_hostname

function geoip_list_hostname( $ip )

Fetches and checks hostname for a given IP.

Prototype

array geoip_open_db( string $ip )

Parameters

ip	(string) An IP-Address (e.g. '100.10.20.2' ).

Returns

An array which will contain the hostname and the result of the hostname-check as int-value.

array(0=>'faked.example.com', 1=>0)

Example

list($hostname, $result) = geoip_list_hostname($_SERVER['REMOTE_ADDR']);

    $hostname     │result│ meaning
──────────────────┼──────┼───────────────────────────────────────────
 faked.google.com │   0  │ hostname faked
dd-112.example.org│   1  │ ok
     200.2.3.1    │   2  │ no hostname
xx3323.example.com│   3  │ hostname has no ip (don't care about this)

Just consider $result >0 as 'real' hostnames.

if($result==0) { // faked }
else { // OK }

geoip_is_proxy

function geoip_is_proxy()

Checks if the actual user ( $_SERVER['REMOTE_ADDR'] ) is behind a proxy.

Prototype

bool geoip_is_proxy( void )

Parameters

Uses

Different $_SERVER[]; variables

Returns

TRUE if the user is behind a proxy. FALSE if there is no evidence for a proxy.

geoip_in_bogons_list

function geoip_in_bogons_list( $ip )

Checks if the given IP is in an unallocated or private address range.

Prototype

bool geoip_in_bogons_list( string $ip )

Parameters

ip	(string) An IP-Address (e.g. '100.10.20.2' ).

Returns

TRUE if the IP is in the bogons-list, FALSE if it is not.

geoip_in_drop_list

function geoip_in_drop_list( $ip )

Checks if the given IP is in spamhaus' drop-list.

DROP (Don't Route Or Peer) is an advisory "drop all traffic" list, consisting of stolen 'zombie' netblocks and netblocks controlled entirely by professional spammers.

Prototype

bool geoip_in_drop_list( string $ip )

Parameters

ip	(string) An IP-Address (e.g. '100.10.20.2' ).

Returns

TRUE if the IP is in drop-list, FALSE if it is not.

function geoip_open_db( $use_cache = FALSE )

Opens GeoIP-database for use.

function geoip_close_db( $gi )

Closes GeoIP-database after use.

function geoip_flag_html( $gi,
$src )

Returns a piece of HTML-code to display a flag.

function geoip_flag_link( $gi,
$src )

Returns an absolute URL to a flag-image.

function geoip_best_ip()

Fetches best matching IP for actual connection.

function geoip_list_ip()

Fetches user-ip and proxy-ip if available.

function geoip_fetch_hostname( $ip )

Fetches hostname for given IP.

function geoip_list_hostname( $ip )

Fetches and checks hostname for a given IP.

function geoip_is_proxy()

Checks if the actual user ( $_SERVER['REMOTE_ADDR'] ) is behind a proxy.

function geoip_in_bogons_list( $ip )

Checks if the given IP is in an unallocated or private address range.

function geoip_in_drop_list( $ip )

Checks if the given IP is in spamhaus' drop-list.