MIN_PHP_VERSION
MIN_PHP_VERSION = '5.2.3'
Min PHP version required for this API.
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);
getTreeFromString( $json, boolean $includeChangeableUserAgentProperties = true) : array
Returns a loaded JSON tree from a string of JSON data.
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.
| $json | ||
| boolean | $includeChangeableUserAgentProperties | Also detect changeable user-agent properties |
The loaded JSON tree
getTreeFromFile(string $filename, boolean $includeChangeableUserAgentProperties = true) : array
Returns a tree from a JSON file.
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.
| string | $filename | The location of the file to read in. |
| boolean | $includeChangeableUserAgentProperties |
&$tree Previously generated tree
getProperties(array $tree, string $userAgent, string|null $cookie = null) : array
Returns an array of known properties (as strings) for the user agent
= 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.
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string|null | $cookie | The contents of the cookie containing the client side properties |
properties Property name => Property value
getPropertiesAsTyped(array $tree, string $userAgent, string|null $cookie = null) : array
Returns an array of known properties (as typed) for the user agent
= 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.
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string|null | $cookie | The contents of the cookie containing the client side properties |
properties. Property name => Typed property value
getProperty(array $tree, string $userAgent, string $property, string|null $cookie = null) : string
Returns a value for the named property for this user agent
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string | $property | The name of the property to return |
| string|null | $cookie | The contents of the cookie containing the client side properties |
property
getPropertyAsString(array $tree, string $userAgent, string $property, string|null $cookie = null) : string
Strongly typed property accessor.
Returns a string property. (Throws an exception if the property is actually of another type.)
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string | $property | The name of the property to return |
| string|null | $cookie | The contents of the cookie containing the client side properties |
property
getPropertyAsBoolean(array $tree, string $userAgent, string $property, string|null $cookie = null) : boolean
Strongly typed property accessor.
Returns a boolean property. (Throws an exception if the property is actually of another type.)
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string | $property | The name of the property to return |
| string|null | $cookie | The contents of the cookie containing the client side properties |
property
getPropertyAsDate(array $tree, string $userAgent, string $property, string|null $cookie = null) : string
Strongly typed property accessor.
Returns a date property. (Throws an exception if the property is actually of another type.)
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string | $property | The name of the property to return |
| string|null | $cookie | The contents of the cookie containing the client side properties |
property
getPropertyAsInteger(array $tree, string $userAgent, string $property, string|null $cookie = null) : integer
Strongly typed property accessor.
Returns an integer property. (Throws an exception if the property is actually of another type.)
| array | $tree | |
| string | $userAgent | String from the device's User-Agent header |
| string | $property | The name of the property to return |
| string|null | $cookie | The contents of the cookie containing the client side properties |
property