Documentation

CarrierApiWeb extends CarrierApi
in package

A small extension to the core CarrierApi to get IP from $_SERVER for current client.

The getProperties() and getProperty() methods in this class extract the most suitable client IP.

Example usage:

$carrierApi = new CarrierApiWeb();
// loading data can be slow - it is recommended wrap the API in a Singleton.
$carrierApi->loadDataFromFile('/path/to/sample.dat');

// get all properties for current client
Properties props = carrierApi.GetProperties(request);

// .... use the properties ....
if (props.ContainsKey("networkOperator") {
   string operatorName = props.Get("networkOperator").AsString();
}

// get a single property
Property countryProp = carrierApi.GetProperty("countryCode");
if (countryProp != null) {
  string countryCode = countryProp.AsString();
}
Tags
copyright

Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved.

author

DeviceAtlas Limited

Table of Contents

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()  : mixed
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
Get the Carrier properties for the current client.
getProperty()  : mixed
Get a specific Property from the current client IP found.
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
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
getIpFromServer()  : string
Get the most suitable IP address from the given request. This function checks the headers defined in CarrierApi::HEADERS_TO_CHECK.

Constants

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'

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

buildDataFile()

public abstract buildDataFile(mixed $dataFileDownloadUrl) : mixed
Parameters
$dataFileDownloadUrl : mixed

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
Tags
throws
DataLoadingException

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

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

Get the Carrier properties for the current client.

public getProperties([mixed $param = null ]) : Properties
Parameters
$param : mixed = null
Return values
Properties

The found properties or null of no properties found.

getProperty()

Get a specific Property from the current client IP found.

public getProperty(mixed $propertyName[, mixed $param = null ]) : mixed

Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once than repeated calls to getProperty().

Parameters
$propertyName : mixed
$param : mixed = null
Tags
throws
InvalidPropertyNameException

Thrown if the property name does not exist.

Return values
mixed

The found 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()

public abstract loadDataFromFile(mixed $jsonDataFilePath) : mixed
Parameters
$jsonDataFilePath : 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
Tags
throws
InvalidPropertyNameException

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

getIpFromServer()

Get the most suitable IP address from the given request. This function checks the headers defined in CarrierApi::HEADERS_TO_CHECK.

private getIpFromServer() : string
Return values
string

The found IP address or null if no IP found.


        
On this page

Search results