Documentation

CarrierApi extends BaseDeviceAtlasApi
in package

Application

The main class for the Carrier Identification API. Used to load the data file and to perform lookups using IPv4 addresses. For usage in a Web App it is recommended to use the CarrierApiWeb (CarrierApiWeb.php) class so you don't have to pass the client's IP address manually.

Please note that it is advisable to load only a single instance of this class to avoid multiple loadings of the data file.

Example usage:

    $ip = '62.40.34.220';
    $carrierApi = new CarrierApi();
    $carrierApi->loadDataFromFile('/path/to/sample.dat');

    // get all properties
    $props = $carrierApi->getProperties($ip);
    // .... use the properties ....
    if ($props->containsKey('networkOperator')) {
        $property = $props->get('networkOperator');
        $operatorName = $property->asString();
        print('networkOperator: ' . $operatorName);
    }

    // get a single property
    $mccProp = $carrierApi->getProperty($ip, 'mcc');
    if ($mccProp !== null) {
        $mcc = $mccProp->asString();
        print('MCC: ' . $mcc);
    }

Please see the code in the Examples directory for additional samples.

Constants

API_VERSION = '1.2.1': Carrier API version
MIN_PHP_VERSION = '5.2.3': Min PHP version required for this API to work

Properties

$HEADERS_TO_CHECK : mixed: A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback.
$data : mixed: Data loaded from the data file
$INVALID_PROP_EX : mixed: Error messages
$MISSING_DATA_EX : mixed: Error messages

Methods

__construct() : mixed: Construct a Carrier API object and load the data file (if path is provided).
buildDataFile() : DataFile
downloadAndLoadDataFile() : mixed
downloadAndLoadDataFileFromUrl() : mixed: Load the DeviceAtlas data file data from a URL.
getDataFileCopyright() : string: Returns the data file copyright text.
getDataFileCreationDate() : string: Returns the data file creation date in ISO8601 format.
getDataFileVersion() : string: Returns the version of the data file.
getDeviceAtlasApiVersion() : string
getIp() : string: Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK.
getProperties() : Properties
getProperty() : Property
getPropertyNames() : array<string|int, mixed>: A set of all the possible property names. The Set contains PropertyName objects that each have a name and an associated data type.
isPublicIp() : bool: An IP address is considered public if it is not in any of the following ranges: <pre> 1) any local address IP: 0
loadDataFromFile() : mixed: Load the data file from the provided path. The data file is reloaded every time this method is called.
reload() : mixed: Downloads a new data file if the existing one is stale.
scheduleReloadAndFinishRequest() : mixed: A secondary register_shutdown_call to make sure the reload method is called as the last one.
dataLoaded() : mixed: Check if the given propertyName is not null and exists in the data file.
extractIp() : mixed: Extracts and cleans an IP address from the headerValue. Some headers such as "X-Forwarded-For" can contain multiple IP addresses such as: clientIP, proxy1, proxy2... This method splits up the headerValue and takes the most appropriate value as the IP.
propertyNameExists() : mixed: Check if the given propertyName is not null and exists in the data file. Calls to this method must be sure that the data object is already loaded.
callFailureCallback() : mixed: Call user defined callback if set.
checkReloadSchedule() : mixed

API_VERSION

Carrier API version


    public
        mixed
    API_VERSION
    = '1.2.1'

MIN_PHP_VERSION

Min PHP version required for this API to work


    public
        mixed
    MIN_PHP_VERSION
    = '5.2.3'

$HEADERS_TO_CHECK

A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback.


    public
    static    mixed
    $HEADERS_TO_CHECK
     = array(
    'x-forwarded-for',
    'client-ip',
    'x-client-ip',
    'rlnclientipaddr',
    // from f5 load balancers
    'proxy-client-ip',
    'wl-proxy-client-ip',
    // weblogic load balancers
    'x-forwarded',
    'forwarded-for',
    'forwarded',
)

$data

Data loaded from the data file


    private
        mixed
    $data

$INVALID_PROP_EX

Error messages


    private
    static    mixed
    $INVALID_PROP_EX
     = 'Property name "%s" does not exist.'

$MISSING_DATA_EX

Error messages


    private
    static    mixed
    $MISSING_DATA_EX
     = 'No data file loaded, load data with loadDataFromFile().'

__construct()

Construct a Carrier API object and load the data file (if path is provided).


    public
                    __construct() : mixed

buildDataFile()


    public
                    buildDataFile(mixed $dataFileDownloadUrl) : DataFile

Parameters

$dataFileDownloadUrl : mixed

Return values

DataFile

downloadAndLoadDataFile()


    public
                    downloadAndLoadDataFile(mixed $dataFileDownloadUrl) : mixed

Parameters

$dataFileDownloadUrl : mixed

downloadAndLoadDataFileFromUrl()

Load the DeviceAtlas data file data from a URL.


    public
                    downloadAndLoadDataFileFromUrl(mixed $dataFile[, mixed $dataFileManager = null ]) : mixed

Schedule a reload if data file is stale. Re-download data file if local data file is corrupted.

Parameters

$dataFile : mixed
$dataFileManager : mixed = null

getDataFileCopyright()

Returns the data file copyright text.


    public
                    getDataFileCopyright() : string

Return values

string —

the copyright

getDataFileCreationDate()

Returns the data file creation date in ISO8601 format.


    public
                    getDataFileCreationDate() : string

Return values

string —

the creationDate

getDataFileVersion()

Returns the version of the data file.


    public
                    getDataFileVersion() : string

Return values

string —

the version

getDeviceAtlasApiVersion()


    public
                    getDeviceAtlasApiVersion() : string

Return values

string

getIp()

Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK.


    public
                    getIp(mixed $keyVals) : string

Parameters

$keyVals : mixed

Return values

string —

The most suitable IP or NULL if a suitable IP could not be found.

getProperties()


    public
                    getProperties(mixed $ipv4) : Properties

Parameters

$ipv4 : mixed

Return values

Properties —

The found properties or null of no properties found.

getProperty()


    public
                    getProperty(mixed $ipv4, mixed $propertyName) : Property

Parameters

$ipv4 : mixed
$propertyName : mixed

Return values

Property —

The Property or null if no property found.

getPropertyNames()

A set of all the possible property names. The Set contains PropertyName objects that each have a name and an associated data type.


    public
                    getPropertyNames() : array<string|int, mixed>

Return values

array<string|int, mixed> —

array of possible property names.

isPublicIp()

An IP address is considered public if it is not in any of the following ranges: <pre> 1) any local address IP: 0


    public
                    isPublicIp(mixed $ip) : bool

a local loopback address range: 127/8
a site local address i.e. IP is in any of the ranges: range: 10/8 range: 172.16/12 range: 192.168/16
a link local address range: 169.254/16

Parameters

$ip : mixed

Return values

bool —

True if it is a public IP, false if the IP is invalid or is not public.

loadDataFromFile()

Load the data file from the provided path. The data file is reloaded every time this method is called.


    public
                    loadDataFromFile(mixed $path) : mixed

Parameters

$path : mixed

reload()

Downloads a new data file if the existing one is stale.


    public
                    reload( $dataFile,  $dataFileManager[,  $isScheduled = false ]) : mixed

Loads data file into API.

Parameters

$dataFile :
$dataFileManager :
$isScheduled : = false

scheduleReloadAndFinishRequest()

A secondary register_shutdown_call to make sure the reload method is called as the last one.


    public
                    scheduleReloadAndFinishRequest( $dataFile,  $dataFileManager) : mixed

Parameters

$dataFile :
$dataFileManager :

dataLoaded()

Check if the given propertyName is not null and exists in the data file.


    protected
                    dataLoaded() : mixed

extractIp()

Extracts and cleans an IP address from the headerValue. Some headers such as "X-Forwarded-For" can contain multiple IP addresses such as: clientIP, proxy1, proxy2... This method splits up the headerValue and takes the most appropriate value as the IP.


    protected
                    extractIp(mixed $headerName, mixed $headerValue) : mixed

Parameters

$headerName : mixed
$headerValue : mixed

propertyNameExists()

Check if the given propertyName is not null and exists in the data file. Calls to this method must be sure that the data object is already loaded.


    protected
                    propertyNameExists(mixed $propertyName) : mixed

Parameters

$propertyName : mixed

callFailureCallback()

Call user defined callback if set.


    private
                    callFailureCallback(Exception $ex,  $dataFile) : mixed

Parameters

$ex : Exception
$dataFile :

checkReloadSchedule()


    private
                    checkReloadSchedule(mixed $dataFile, mixed $dataFileManager[, mixed $forceReload = false ]) : mixed

Parameters

$dataFile : mixed
$dataFileManager : mixed
$forceReload : mixed = false

CarrierApi extends BaseDeviceAtlasApi in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

API_VERSION

MIN_PHP_VERSION

Properties

$HEADERS_TO_CHECK

$data

$INVALID_PROP_EX

$MISSING_DATA_EX

Methods

__construct()

Tags

buildDataFile()

Parameters

Return values

downloadAndLoadDataFile()

Parameters

downloadAndLoadDataFileFromUrl()

Parameters

Tags

getDataFileCopyright()

Return values

getDataFileCreationDate()

Return values

getDataFileVersion()

Return values

getDeviceAtlasApiVersion()

Return values

getIp()

Parameters

Return values

getProperties()

Parameters

Tags

Return values

getProperty()

Parameters

Tags

Return values

getPropertyNames()

Return values

isPublicIp()

Parameters

Return values

loadDataFromFile()

Parameters

Tags

reload()

Parameters

scheduleReloadAndFinishRequest()

Parameters

dataLoaded()

extractIp()

Parameters

propertyNameExists()

Parameters

Tags

callFailureCallback()

Parameters

checkReloadSchedule()

Parameters

CarrierApi extends BaseDeviceAtlasApi
in package

Application