TOP

Mobi_Mtld_DA_Device_DeviceApi

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.
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 (...
Package
Mobi\Mtld\DA\Device
Version
2.1.0
Author
DeviceAtlas Limited
Copyright
Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved.

Constants

API_VERSION = '2.1'

Api version.

MIN_PHP_VERSION = '5.2.3'

Minimum PHP version required for this API to run. *

Static Methods

getApiVersion

string Mobi_Mtld_DA_Device_DeviceApi::getApiVersion()

Get DeviceApi version.

Returns

string
DeviceApi version

Methods

__construct

Mobi_Mtld_DA_Device_DeviceApi $obj = new Mobi_Mtld_DA_Device_DeviceApi(
    Mobi_Mtld_DA_Device_Config config
)

Constructs a DeviceApi instance with custom configs.

See also
Mobi_Mtld_DA_Device_Config

Arguments

    config (Mobi_Mtld_DA_Device_Config)
    An instance of Config, you can change the DeviceAtlas API configs by creating an instance or Config and setting your preferences config values then passing the instance to the DeviceApi constructor. null=use default configs.

Returns

void

getDataCreationTimestamp

string $obj->getDataCreationTimestamp()

Get the device data creation (JSON file) timestamp.

Returns

string
The string data creation timestamp

getDataRevision

int $obj->getDataRevision()

Get the device data generation revision.

Returns

int
Data generation revision

getDataVersion

string $obj->getDataVersion()

Get the device data (JSON file) version.

Returns

string
The data version

getLookupSource

string $obj->getLookupSource()

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

Returns

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

getProperties

Mobi_Mtld_DA_Properties $obj->getProperties(
    string userAgent,
    string clientSideProperties=null
)

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.

Arguments

    userAgent (string)
    The User-Agent string
    clientSideProperties=null (string)
    The contents of the cookie containing the client side properties

Returns

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

Throws

getProperties 

Mobi_Mtld_DA_Properties $obj->getProperties(
    array headers,
    string clientSideProperties=null
)

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.

Arguments

    headers (array)
    Client's request HTTP headers
    clientSideProperties=null (string)
    The contents of the cookie containing the client side properties

Returns

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

Throws

getPropertiesFromUa

Mobi_Mtld_DA_Properties $obj->getPropertiesFromUa(
    string userAgent,
    string clientSideProperties=null
)

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.

Arguments

    userAgent (string)
    The User-Agent string
    clientSideProperties=null (string)
    The contents of the cookie containing the client side properties

Returns

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

Throws

getPropertyNames

array $obj->getPropertyNames()

Get a set of available device property names.

Returns

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

loadDataFromFile

void $obj->loadDataFromFile(string jsonDataFilePath)

Load the DeviceAtlas device detection data into the API from a JSON file. The JSON data file is provided by the DeviceAtlas web-site.

Arguments

    jsonDataFilePath (string)
    Path to the JSON file

Returns

void

Throws

loadDataFromString

void $obj->loadDataFromString(string data)

Load the DeviceAtlas device detection data into the API from a string. The JSON data file is provided by the DeviceAtlas web-site.

Arguments

    data (string)
    DeviceAtlas device data

Returns

void

Throws

setConfig

void $obj->setConfig(Mobi_Mtld_DA_Device_Config $config)

Set new config settings via a new Config object and drop current cache.

Arguments

Returns

void