Mobi_Mtld_DA_Api
in package
Used to load the recognition tree and perform lookups of all properties, or individual properties.
Note: Due to limitations in the level of recursion allowed, versions of PHP older than 5.2.3 will be unable to load the JSON data file. i.e. DeviceAtlas must be run with PHP version 5.2.3 or later.
Typical usage is as follows:
$tree = Mobi_Mtld_DA_Api::getTreeFromFile("json/sample.json");
$props = Mobi_Mtld_DA_Api::getProperties($tree, "Nokia6680...");
Note that you should normally use the user-agent that was received in the device's HTTP request. In a PHP environment, you would do this as follows:
$ua = $_SERVER['HTTP_USER_AGENT']; $displayWidth = Mobi_Mtld_DA_Api::getPropertyAsInteger($tree, $ua, "displayWidth");
(Also note the use of the strongly typed property accessor)
Third-party Browsers
In some contexts, the user-agent you want to recognise may have been provided in a different header. Opera's mobile browser, for example, makes requests via an HTTP proxy, which rewrites the headers. in that case, the original device's user-agent is in the HTTP_X_OPERAMINI_PHONE_UA header, and the following code could be used:
$opera_header = "HTTP_X_OPERAMINI_PHONE_UA";
if (array_key_exists($opera_header, $_SERVER) {
$ua = $_SERVER[$opera_header];
} else {
$ua = $_SERVER['HTTP_USER_AGENT'];
}
$displayWidth = Mobi_Mtld_DA_Api::getPropertyAsInteger($tree, $ua, "displayWidth");
Client side properties
Client side properties can be collected and merged into the results by using the DeviceAtlas Javascript detection file. The results from the client side are sent to the server inside a cookie. The contents of this cookie can be passed to the DeviceAtlas getProperty and getProperties methods. The client side properties over-ride any data file properties and also serve as an input into additional logic to determine other properties such as the iPhone models that are otherwise not detectable. The following code shows how this can be done:
$ua = $_SERVER['HTTP_USER_AGENT'];
// Get the cookie containing the client side properties
$cookie_contents = null;
if (isset($_COOKIE['DAPROPS'])){
$cookie_contents = $_COOKIE['DAPROPS'];
}
$props = Mobi_Mtld_DA_Api::getProperties($tree, $ua, $cookie_contents);
Tags
Table of Contents
- MIN_PHP_VERSION = '5.2.3'
- Min PHP version required for this API.
- getApiRevision() : int
- Returns the revision number of this API
- getProperties() : array<string|int, mixed>
- Returns an array of known properties (as strings) for the user agent
- getPropertiesAsTyped() : array<string|int, mixed>
- Returns an array of known properties (as typed) for the user agent
- getProperty() : string
- Returns a value for the named property for this user agent
- getPropertyAsBoolean() : bool
- Strongly typed property accessor.
- getPropertyAsDate() : string
- Strongly typed property accessor.
- getPropertyAsInteger() : int
- Strongly typed property accessor.
- getPropertyAsString() : string
- Strongly typed property accessor.
- getTreeFromFile() : array<string|int, mixed>
- Returns a tree from a JSON file.
- getTreeFromString() : array<string|int, mixed>
- Returns a loaded JSON tree from a string of JSON data.
- getTreeGeneration() : string
- Get the generation date for this tree.
- getTreeGenerationAsTimestamp() : int
- Get the generation date for this tree as a UNIX timestamp.
- getTreeRevision() : int
- Returns the revision number of the tree
- listProperties() : array<string|int, mixed>
- Returns all properties available for all user agents in this tree, with their data type names.
- getPropertyTypeAsString() : mixed
- Convert interface data types to tree property types
Constants
MIN_PHP_VERSION
Min PHP version required for this API.
public
mixed
MIN_PHP_VERSION
= '5.2.3'
Methods
getApiRevision()
Returns the revision number of this API
public
static getApiRevision() : int
Return values
int —revision
getProperties()
Returns an array of known properties (as strings) for the user agent
public
static getProperties(array<string|int, mixed> &$tree, string $userAgent[, string|null $cookie = null ]) : array<string|int, mixed>
= or =
Returns an array of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
array<string|int, mixed> —properties Property name => Property value
getPropertiesAsTyped()
Returns an array of known properties (as typed) for the user agent
public
static getPropertiesAsTyped(array<string|int, mixed> &$tree, string $userAgent[, string|null $cookie = null ]) : array<string|int, mixed>
= or =
Returns an array of known properties merged with properties from the client side JavaScript. The client side JavaScript sets a cookie with collected properties. The contents of this cookie must be passed to this method for it to work. The client properties over-ride any properties discovered from the main JSON data file.
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
array<string|int, mixed> —properties. Property name => Typed property value
getProperty()
Returns a value for the named property for this user agent
public
static getProperty(array<string|int, mixed> &$tree, string $userAgent, string $property[, string|null $cookie = null ]) : string
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $property : string
-
The name of the property to return
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
string —property
getPropertyAsBoolean()
Strongly typed property accessor.
public
static getPropertyAsBoolean(array<string|int, mixed> &$tree, string $userAgent, string $property[, string|null $cookie = null ]) : bool
Returns a boolean property. (Throws an exception if the property is actually of another type.)
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $property : string
-
The name of the property to return
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
bool —property
getPropertyAsDate()
Strongly typed property accessor.
public
static getPropertyAsDate(array<string|int, mixed> &$tree, string $userAgent, string $property[, string|null $cookie = null ]) : string
Returns a date property. (Throws an exception if the property is actually of another type.)
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $property : string
-
The name of the property to return
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
string —property
getPropertyAsInteger()
Strongly typed property accessor.
public
static getPropertyAsInteger(array<string|int, mixed> &$tree, string $userAgent, string $property[, string|null $cookie = null ]) : int
Returns an integer property. (Throws an exception if the property is actually of another type.)
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $property : string
-
The name of the property to return
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
int —property
getPropertyAsString()
Strongly typed property accessor.
public
static getPropertyAsString(array<string|int, mixed> &$tree, string $userAgent, string $property[, string|null $cookie = null ]) : string
Returns a string property. (Throws an exception if the property is actually of another type.)
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
- $userAgent : string
-
String from the device's User-Agent header
- $property : string
-
The name of the property to return
- $cookie : string|null = null
-
The contents of the cookie containing the client side properties
Tags
Return values
string —property
getTreeFromFile()
Returns a tree from a JSON file.
public
static getTreeFromFile(string $filename[, bool $includeChangeableUserAgentProperties = true ]) : array<string|int, mixed>
Use an absolute path name to be sure of success if the current working directory is not clear.
Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set includeChangeableUserAgentProperties to false.
Parameters
- $filename : string
-
The location of the file to read in.
- $includeChangeableUserAgentProperties : bool = true
Tags
Return values
array<string|int, mixed> —&$tree Previously generated tree
getTreeFromString()
Returns a loaded JSON tree from a string of JSON data.
public
static getTreeFromString(string &$json[, bool $includeChangeableUserAgentProperties = true ]) : array<string|int, mixed>
Some properties cannot be known before runtime and can change from user-agent to user-agent. The most common of these are the OS Version and the Browser Version. This API is able to dynamically detect these changing properties but introduces a small overhead to do so. To disable returning these extra properties set includeChangeableUserAgentProperties to false.
Parameters
- $json : string
-
The string of json data.
- $includeChangeableUserAgentProperties : bool = true
-
Also detect changeable user-agent properties
Tags
Return values
array<string|int, mixed> —The loaded JSON tree
getTreeGeneration()
Get the generation date for this tree.
public
static getTreeGeneration(array<string|int, mixed> &$tree) : string
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
Return values
string —The time/date the tree was generated.
getTreeGenerationAsTimestamp()
Get the generation date for this tree as a UNIX timestamp.
public
static getTreeGenerationAsTimestamp(array<string|int, mixed> &$tree) : int
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
Return values
int —The time/date the tree was generated.
getTreeRevision()
Returns the revision number of the tree
public
static getTreeRevision(array<string|int, mixed> &$tree) : int
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
Return values
int —revision
listProperties()
Returns all properties available for all user agents in this tree, with their data type names.
public
static listProperties(array<string|int, mixed> &$tree) : array<string|int, mixed>
Parameters
- $tree : array<string|int, mixed>
-
Previously generated tree
Return values
array<string|int, mixed> —properties
getPropertyTypeAsString()
Convert interface data types to tree property types
private
static getPropertyTypeAsString(mixed $type) : mixed
Parameters
- $type : mixed