Static Public Member Functions
static	getTreeFromString (&$json, $includeChangeableUserAgentProperties=true)
static	getTreeFromFile ($filename, $includeChangeableUserAgentProperties=true)
static	getTreeGeneration (array &$tree)
static	getTreeGenerationAsTimestamp (array &$tree)
static	getTreeRevision (array &$tree)
static	getApiRevision ()
static	listProperties (array &$tree)
static	getProperties (array &$tree, $userAgent, $cookie=null)
static	getPropertiesAsTyped (array &$tree, $userAgent, $cookie=null)
static	getProperty (array &$tree, $userAgent, $property, $cookie=null)
static	getPropertyAsBoolean (array &$tree, $userAgent, $property, $cookie=null)
static	getPropertyAsDate (array &$tree, $userAgent, $property, $cookie=null)
static	getPropertyAsInteger (array &$tree, $userAgent, $property, $cookie=null)
static	getPropertyAsString (array &$tree, $userAgent, $property, $cookie=null)
static	_seekPostWalkProperties (array &$node, $string, array &$properties)

Public Attributes
const	API_ID = 1
const	MIN_PHP_VERSION = '5.2.3'
const	JSON_INFO = '$'
const	CLIENT_PROPS_HANDLER = "_cprops"
const	UA_PROPS_HANDLER = "_uaprops"
const	ID_TO_PROPERTIES_WITH_TYPE = "p"
const	PROPERTIES_WITH_TYPE_TO_ID = "pr"
const	PROPERTIES_WITHOUT_TYPE_TO_ID = "pn"
const	ID_TO_PROPERTY_WITHOUT_TYPE = "pnr"
const	ID_TO_VALUES = "v"
const	MAIN_TREE_BRANCH = "t"
const	REGEX = "r"
const	COMPILED_REGEX = "creg"

Detailed Description

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

Member Function Documentation

static Mobi_Mtld_DA_Api::_seekPostWalkProperties	(	array &	$node,
			$string,
		array &	$properties
	)

static

Used only by the TreeOptimizer class to get the PostWalk User-Agents properties.

NOT for public use

Parameters

array	&$node
string	$string
array	&$properties

Returns: array properties

static Mobi_Mtld_DA_Api::getApiRevision ( )

static

Returns the revision number of this API

Returns: integer revision

static Mobi_Mtld_DA_Api::getProperties	(	array &	$tree,
			$userAgent,
			$cookie = `null`
	)

static

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.

Parameters

array	&$tree	Previously generated tree
string	$userAgent	String from the device's User-Agent header
string \| null	$cookie	The contents of the cookie containing the client side properties

Returns: array properties Property name => Property value

Exceptions

Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getPropertiesAsTyped	(	array &	$tree,
			$userAgent,
			$cookie = `null`
	)

static

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.

Parameters

array	&$tree	Previously generated tree
string	$userAgent	String from the device's User-Agent header
string \| null	$cookie	The contents of the cookie containing the client side properties

Returns: array properties. Property name => Typed property value

Exceptions

Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getProperty	(	array &	$tree,
			$userAgent,
			$property,
			$cookie = `null`
	)

static

Returns a value for the named property for this user agent

Parameters

array	&$tree	Previously generated 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

Returns: string property

Exceptions

Mobi_Mtld_Da_Exception_UnknownPropertyException
Mobi_Mtld_Da_Exception_InvalidPropertyException
Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getPropertyAsBoolean	(	array &	$tree,
			$userAgent,
			$property,
			$cookie = `null`
	)

static

Strongly typed property accessor.

Returns a boolean property. (Throws an exception if the property is actually of another type.)

Parameters

array	&$tree	Previously generated 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

Returns: boolean property

Exceptions

Mobi_Mtld_Da_Exception_UnknownPropertyException
Mobi_Mtld_Da_Exception_InvalidPropertyException
Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getPropertyAsDate	(	array &	$tree,
			$userAgent,
			$property,
			$cookie = `null`
	)

static

Strongly typed property accessor.

Returns a date property. (Throws an exception if the property is actually of another type.)

Parameters

array	&$tree	Previously generated 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

Returns: string property

Exceptions

Mobi_Mtld_Da_Exception_UnknownPropertyException
Mobi_Mtld_Da_Exception_InvalidPropertyException
Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getPropertyAsInteger	(	array &	$tree,
			$userAgent,
			$property,
			$cookie = `null`
	)

static

Strongly typed property accessor.

Returns an integer property. (Throws an exception if the property is actually of another type.)

Parameters

array	&$tree	Previously generated 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

Returns: integer property

Exceptions

Mobi_Mtld_Da_Exception_UnknownPropertyException
Mobi_Mtld_Da_Exception_InvalidPropertyException
Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getPropertyAsString	(	array &	$tree,
			$userAgent,
			$property,
			$cookie = `null`
	)

static

Strongly typed property accessor.

Returns a string property. (Throws an exception if the property is actually of another type.)

Parameters

array	&$tree	Previously generated 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

Returns: string property

Exceptions

Mobi_Mtld_Da_Exception_UnknownPropertyException
Mobi_Mtld_Da_Exception_InvalidPropertyException
Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getTreeFromFile	(	$filename,
		$includeChangeableUserAgentProperties = `true`
	)

static

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.

Parameters

string	$filename	The location of the file to read in.
boolean	$includeChangeableUserAgentProperties

Returns: array &$tree Previously generated tree

Exceptions

Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getTreeFromString	(	&	$json,
			$includeChangeableUserAgentProperties = `true`
	)

static

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.

Parameters

string	&$json	The string of json data.
boolean	$includeChangeableUserAgentProperties	Also detect changeable user-agent properties

Returns: array The loaded JSON tree

Exceptions

Mobi_Mtld_Da_Exception_JsonException

static Mobi_Mtld_DA_Api::getTreeGeneration ( array & $tree )

static

Get the generation date for this tree.

Parameters

array &$tree Previously generated tree

Returns: string The time/date the tree was generated.

static Mobi_Mtld_DA_Api::getTreeGenerationAsTimestamp ( array & $tree )

static

Get the generation date for this tree as a UNIX timestamp.

Parameters

array &$tree Previously generated tree

Returns: integer The time/date the tree was generated.

static Mobi_Mtld_DA_Api::getTreeRevision ( array & $tree )

static

Returns the revision number of the tree

Parameters

array &$tree Previously generated tree

Returns: integer revision

static Mobi_Mtld_DA_Api::listProperties ( array & $tree )

static

Returns all properties available for all user agents in this tree, with their data type names.

Parameters

array &$tree Previously generated tree

Returns: array properties

The documentation for this class was generated from the following file:

src/Mobi/Mtld/DA/Api.php

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation