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
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
$config
protected
mixed
$config
$LANGUAGE_HEADER
protected
static mixed
$LANGUAGE_HEADER
= 'accept-language'
$tree
protected
mixed
$tree
$treeCached
protected
mixed
$treeCached
$PROPERTY_NAME_LANGUAGE
private
static mixed
$PROPERTY_NAME_LANGUAGE
= 'language'
$PROPERTY_NAME_LANGUAGE_LOCALE
private
static mixed
$PROPERTY_NAME_LANGUAGE_LOCALE
= 'languageLocale'
Methods
__construct()
Constructs a DeviceApi instance with custom configs.
public
__construct([Mobi_Mtld_DA_Device_Config $config = null ]) : mixed
Parameters
- $config : Mobi_Mtld_DA_Device_Config = null
Tags
Return values
mixed —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
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
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
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 —loadDataFromFile()
Load the DeviceAtlas device detection data into the API from a JSON file.
public
loadDataFromFile(mixed $jsonDataFilePath) : mixed
The JSON data file is provided by the DeviceAtlas web-site.
Parameters
- $jsonDataFilePath : mixed
Tags
Return values
mixed —loadDataFromString()
Load the DeviceAtlas device detection data into the API from a string.
public
loadDataFromString(mixed $data) : mixed
The JSON data file is provided by the DeviceAtlas web-site.
Parameters
- $data : mixed
Tags
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
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
Return values
mixed —setConfig()
Set new config settings via a new Config object and drop current cache.
public
setConfig([Mobi_Mtld_DA_Device_Config $config = null ]) : mixed
Parameters
- $config : Mobi_Mtld_DA_Device_Config = null
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
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