Documentation

Mobi_Mtld_DA_Carrier_CarrierApi extends BaseDeviceAtlasApi
in package

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.

Tags
copyright

Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. https://deviceatlas.com

author

DeviceAtlas Limited

Table of Contents

API_VERSION  = 'DEVICEATLAS_API_VERSION'
Carrier API version
MIN_PHP_VERSION  = '5.2.3'
Min PHP version required for this API to work
$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
__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()  : Mobi_Mtld_DA_Properties
getProperty()  : Mobi_Mtld_DA_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

Constants

API_VERSION

Carrier API version

public mixed API_VERSION = 'DEVICEATLAS_API_VERSION'

MIN_PHP_VERSION

Min PHP version required for this API to work

public mixed MIN_PHP_VERSION = '5.2.3'

Properties

$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().'

Methods

__construct()

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

public __construct() : mixed
Tags
throws
Exception

If PHP version is less than required

Return values
mixed

buildDataFile()

public buildDataFile(mixed $dataFileDownloadUrl) : DataFile
Parameters
$dataFileDownloadUrl : mixed
Return values
DataFile

downloadAndLoadDataFile()

public downloadAndLoadDataFile(mixed $dataFileDownloadUrl) : mixed
Parameters
$dataFileDownloadUrl : mixed
Return values
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
Tags
throws
Mobi_Mtld_DA_Exception_DataFileException

when there is a problem downloading or loading the data file.

Return values
mixed

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) : Mobi_Mtld_DA_Properties
Parameters
$ipv4 : mixed
Tags
overload

Get the Carrier properties for a given IP address.

overload

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

Return values
Mobi_Mtld_DA_Properties

The found properties or null of no properties found.

getProperty()

public getProperty(mixed $ipv4, mixed $propertyName) : Mobi_Mtld_DA_Property
Parameters
$ipv4 : mixed
$propertyName : mixed
Tags
overload

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().

overload

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().

throws
Mobi_Mtld_DA_Exception_InvalidPropertyNameException

Thrown if the property name does not exist.

throws
Mobi_Mtld_DA_Exception_InvalidPropertyNameException

Thrown if the property name does not exist.

Return values
Mobi_Mtld_DA_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
  1. a local loopback address range: 127/8

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

  3. 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
Tags
throws
IOException

Thrown when there is a problem loading the file.

throws
Mobi_Mtld_DA_Exception_DataFileException

Thrown when there is a problem with the data file.

Return values
mixed

reload()

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

public reload( $dataFile,  $dataFileManager) : mixed

Loads data file into API.

Parameters
$dataFile :
$dataFileManager :
Return values
mixed

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 :
Return values
mixed

dataLoaded()

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

protected dataLoaded() : mixed
Return values
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
Return values
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
Tags
throws
Mobi_Mtld_DA_Exception_InvalidPropertyNameException
Return values
mixed

callFailureCallback()

Call user defined callback if set.

private callFailureCallback(Exception $ex,  $dataFile) : mixed
Parameters
$ex : Exception
$dataFile :
Return values
mixed

checkReloadSchedule()

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

Search results