Documentation

Mobi_Mtld_DA_Device_DeviceApi extends BaseDeviceAtlasApi
in package

The DeviceAtlas device detection API provides a way to detect devices based on the HTTP headers. Using the headers, the API returns device properties such as screen width, screen height, is mobile, vendor, model etc. If you want to use the DeviceAtlas API for web applications then it is recommended to use DeviceApiWeb instead of this library.<br/> The DeviceApiWeb is preferred when you want to get the properties from a real-time detection on user's device in a web application.

The DeviceApi is preferred when you want to get the properties from an off-line user-agent list or header set.

To get the most accurate results: 1- Pass the whole HTTP headers. 2- Use the DeviceAtlas client-side-component and pass the result.

Valid inputs are:
$deviceApi->getProperties((array) headers, string clientSide)
$deviceApi->getProperties((array) headers)
$deviceApi->getProperties(string userAgent, string clientSide)
$deviceApi->getProperties(string userAgent)

Example usage:

$headers = array(
    "user-agent"      => "...",
    "accept-language" => "...",
    // add any other available header...
);

// require_once "/PATH/TO/Api/Device/DeviceApi.php";
$deviceApi = new Mobi_Mtld_DA_Device_DeviceApi();

try {
    $deviceApi->loadDataFromFile("/path/to/datafile.json");

    // get all properties from the headers
    $props = $deviceApi->getProperties($headers);

    // .... use the properties ....
    if ($props->contains("isMobilePhone", true)) {
        // it is a mobile phone
    }

    // check if property exists then get the property value
    $displayWidth = $props->containsKey("displayWidth")?
        $props->get("displayWidth")->asInteger(): 100;

    // the most easy way to get a property value
    $deviceModel = $props->model; // null or string
} catch (...
Tags
version
2.1.0
author

DeviceAtlas Limited

copyright

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

Table of Contents

API_VERSION  = 'DEVICEATLAS_API_VERSION'
Api version.
LOOKUP_SOURCE_CACHE  = 'cache'
LOOKUP_SOURCE_OPTIMIZED_TREE  = 'optimized tree'
LOOKUP_SOURCE_TREE  = 'tree'
MIN_PHP_VERSION  = '5.2.3'
Minimum PHP version required for this API to run. *
$config  : mixed
$LANGUAGE_HEADER  : mixed
$tree  : mixed
$treeCached  : mixed
$PROPERTY_NAME_LANGUAGE  : mixed
$PROPERTY_NAME_LANGUAGE_LOCALE  : mixed
__construct()  : mixed
Constructs a DeviceApi instance with custom configs.
buildDataFile()  : mixed
downloadAndLoadDataFile()  : mixed
downloadAndLoadDataFileFromUrl()  : mixed
Load the DeviceAtlas data file data from a URL.
getApiVersion()  : string
Get DeviceApi version.
getDataCreationTimestamp()  : string
Get the device data creation (JSON file) timestamp.
getDataRevision()  : int
Get the device data generation revision.
getDataVersion()  : string
Get the device data (JSON file) version.
getDeviceAtlasApiVersion()  : mixed
getLookupSource()  : string
Get the source properties fetch source to be used for debugging.
getProperties()  : Mobi_Mtld_DA_Properties
getPropertiesFromUa()  : Mobi_Mtld_DA_Properties
Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component).
getPropertyNames()  : array<string|int, mixed>
Get a set of available device property names.
getTreeCache()  : mixed
loadDataFromFile()  : mixed
Load the DeviceAtlas device detection data into the API from a JSON file.
loadDataFromString()  : mixed
Load the DeviceAtlas device detection data into the API from a string.
loadTreeFromJsonFilePath()  : 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.
setConfig()  : mixed
Set new config settings via a new Config object and drop current cache.
setTreeCache()  : mixed
addLanguageProperties()  : mixed
Get the Accept-Language header and add language properties to the property list
callFailureCallback()  : mixed
Call user defined callback if set.
checkReloadSchedule()  : mixed
getPropertyTypeAsByte()  : mixed
Convert tree property types to interface data types
normaliseKeys()  : mixed
Normalise the HTTP header keys, replaces "_" with "-" and removes any HTTP_ prefix

Constants

API_VERSION

Api version.

public mixed API_VERSION = 'DEVICEATLAS_API_VERSION'

LOOKUP_SOURCE_CACHE

public mixed LOOKUP_SOURCE_CACHE = 'cache'

LOOKUP_SOURCE_OPTIMIZED_TREE

public mixed LOOKUP_SOURCE_OPTIMIZED_TREE = 'optimized tree'

LOOKUP_SOURCE_TREE

public mixed LOOKUP_SOURCE_TREE = 'tree'

MIN_PHP_VERSION

Minimum PHP version required for this API to run. *

public mixed MIN_PHP_VERSION = '5.2.3'

Properties

$LANGUAGE_HEADER

protected static mixed $LANGUAGE_HEADER = 'accept-language'

$PROPERTY_NAME_LANGUAGE

private static mixed $PROPERTY_NAME_LANGUAGE = 'language'

$PROPERTY_NAME_LANGUAGE_LOCALE

private static mixed $PROPERTY_NAME_LANGUAGE_LOCALE = 'languageLocale'

Methods

buildDataFile()

public 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
Mobi_Mtld_DA_Exception_DataFileException

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

Return values
mixed —

getApiVersion()

Get DeviceApi version.

public static getApiVersion() : string
Return values
string —

DeviceApi version

getDataCreationTimestamp()

Get the device data creation (JSON file) timestamp.

public getDataCreationTimestamp() : string
Return values
string —

The string data creation timestamp

getDataRevision()

Get the device data generation revision.

public getDataRevision() : int
Return values
int —

Data generation revision

getDataVersion()

Get the device data (JSON file) version.

public getDataVersion() : string
Return values
string —

The data version

getDeviceAtlasApiVersion()

public getDeviceAtlasApiVersion() : mixed
Return values
mixed —

getLookupSource()

Get the source properties fetch source to be used for debugging.

public getLookupSource() : string
Return values
string —

The value of one this constants: LOOKUP_SOURCE_TREE or LOOKUP_SOURCE_OPTIMIZED_TREE or LOOKUP_SOURCE_CACHE

getProperties()

public getProperties([mixed $headers = null ][, mixed $clientSideProperties = null ]) : Mobi_Mtld_DA_Properties
Parameters
$headers : mixed = null
$clientSideProperties : mixed = null
Tags
overload

Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component). The DeviceAtlas client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will over-ride any properties discovered from the main JSON data file.

overload

Get the properties for a set of HTTP headers merged with properties from the client side component. The DeviceApi gets all the request HTTP headers and will precisely detect the device and find property values by all usable headers. Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component). The DeviceAtlas client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will over-ride any properties discovered from the main JSON data file.

throws
Mobi_Mtld_DA_Exception_ClientPropertiesException
throws
Mobi_Mtld_DA_Exception_ClientPropertiesException
Return values
Mobi_Mtld_DA_Properties —

A set of properties (Property objects) wrapped in a Properties object

getPropertiesFromUa()

Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component).

public getPropertiesFromUa(mixed $userAgent[, mixed $clientSideProperties = null ]) : Mobi_Mtld_DA_Properties

The DeviceAtlas client-side component (JavaScript library) collects the client-side properties and puts them in a cookie. The contents of this cookie must be passed to this method. The client properties will over-ride any properties discovered from the main JSON data file.

Parameters
$userAgent : mixed
$clientSideProperties : mixed = null
Tags
throws
Mobi_Mtld_DA_Exception_ClientPropertiesException
Return values
Mobi_Mtld_DA_Properties —

A set of properties (Property objects) wrapped in a Properties object

getPropertyNames()

Get a set of available device property names.

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

A set of available device property names as PropertyName objects. A PropertyName object holds a property-name and it's data-type

getTreeCache()

public getTreeCache() : mixed
Return values
mixed —

loadTreeFromJsonFilePath()

public loadTreeFromJsonFilePath(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) : 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 —

setTreeCache()

public setTreeCache(mixed $treeCached) : mixed
Parameters
$treeCached : mixed
Return values
mixed —

addLanguageProperties()

Get the Accept-Language header and add language properties to the property list

private addLanguageProperties(mixed $acceptLanguage, mixed &$treeProperties) : mixed
Parameters
$acceptLanguage : mixed
$treeProperties : mixed
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 —

getPropertyTypeAsByte()

Convert tree property types to interface data types

private static getPropertyTypeAsByte(mixed $typeChar) : mixed
Parameters
$typeChar : mixed
Return values
mixed —

normaliseKeys()

Normalise the HTTP header keys, replaces "_" with "-" and removes any HTTP_ prefix

private static normaliseKeys(mixed $keyVals) : mixed
Parameters
$keyVals : mixed
Return values
mixed —

Search results