TOP

Mobi_Mtld_DA_Carrier_CarrierApi

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.
Copyright
Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved.
Author
DeviceAtlas Limited

Constants

MIN_PHP_VERSION = '5.2.3'

Min PHP version required for this API to work

VERSION = 'API-VERSION'

Carrier API version

Static Properties

HEADERS_TO_CHECK = array

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',
    )

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.

Methods

__construct

Mobi_Mtld_DA_Carrier_CarrierApi $obj = new Mobi_Mtld_DA_Carrier_CarrierApi()

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

Returns

void

Throws

  • Exception If PHP version is less than required

getDataFileCopyright

string $obj->getDataFileCopyright()

Returns the data file copyright text.

Returns

string
the copyright

getDataFileCreationDate

string $obj->getDataFileCreationDate()

Returns the data file creation date in ISO8601 format.

Returns

string
the creationDate

getDataFileVersion

string $obj->getDataFileVersion()

Returns the version of the data file.

Returns

string
the version

getIp

string $obj->getIp(array keyVals)

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

Arguments

    keyVals (array)
    array of headers

Returns

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

getProperties

Mobi_Mtld_DA_Properties $obj->getProperties(string | int ipv4)

Get the Carrier properties for a given IP address.

Arguments

    ipv4 (string | int)
    The IP address to find carrier properties for.

Returns

Mobi_Mtld_DA_Properties
The found properties or null of no properties found.

getProperties 

Mobi_Mtld_DA_Properties $obj->getProperties(array ipv4)

Get the Carrier properties for a given set of HTTP headers.

Arguments

    ipv4 (array)
    An array of HTTP headers, the keys will be normalized.

Returns

Mobi_Mtld_DA_Properties
The found properties or null of no properties found.

getProperty

Mobi_Mtld_DA_Property $obj->getProperty(string | int ipv4, string propertyName)

Try and get a specific property for a given IP address. Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once than repeated calls to getProperty().

Arguments

    ipv4 (string | int)
    The IP address to find carrier properties for.
    propertyName (string)
    The name of the property to return

Returns

Mobi_Mtld_DA_Property
The Property or null if no property found.

Throws

  • Mobi_Mtld_DA_Exception_InvalidPropertyNameException Thrown if the property name does not exist.

getProperty 

Mobi_Mtld_DA_Property $obj->getProperty(array ipv4, string propertyName)

Try and get a specific property for a given IP address. Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once than repeated calls to getProperty().

Arguments

    ipv4 (array)
    An array of HTTP headers, the keys will be normalized.
    propertyName (string)
    The name of the property to return

Returns

Mobi_Mtld_DA_Property
The Property or null if no property found.

Throws

  • Mobi_Mtld_DA_Exception_InvalidPropertyNameException Thrown if the property name does not exist.

getPropertyNames

array $obj->getPropertyNames()

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

Returns

array
array of possible property names.

isPublicIp

boolean $obj->isPublicIp(string ip)

An IP address is considered public if it is not in any of the following ranges: 

  1) any local address
     IP:  0

  2) a local loopback address
     range:  127/8

  3) a site local address i.e. IP is in any of the ranges:
     range:  10/8
     range:  172.16/12
     range:  192.168/16

  4) a link local address
     range:  169.254/16

Arguments

    ip (string)
    The IP address to check

Returns

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

loadDataFromFile

void $obj->loadDataFromFile(string path)

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

Arguments

    path (string)
    The path on disk to the carrier data file.

Returns

void

Throws