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 2026. All Rights Reserved.

author

DeviceAtlas Limited

Table of Contents

API_VERSION  = '1.2.1'
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()  : 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

Return values
mixed —

buildDataFile()

public abstract buildDataFile(mixed $dataFileDownloadUrl) : mixed
Parameters
$dataFileDownloadUrl : mixed
Return values
mixed —

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
DataLoadingException

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

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
Return values
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
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
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 —

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.

Search results