\DeviceAtlas\DeviceDeviceApi

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.<br/><br/>

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 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 (...

Summary

Methods
Properties
Constants
buildDataFile()
loadDataFromFile()
downloadAndLoadDataFileFromUrl()
scheduleReloadAndFinishRequest()
reload()
__construct()
loadDataFromString()
saveDataToCache()
getPropertyNames()
getApiVersion()
getDataVersion()
getDataCreationTimestamp()
getDataCreationIso8601()
getProperties()
downloadAndLoadDataFile()
No public properties found
API_ID
API_VERSION
MIN_PHP_VERSION
XMSG_PROBLEM_READING_FROM_STRING
XMSG_FILE_NOT_FOUND
XMSG_MISSING_DATA
LOOKUP_SOURCE_TREE
LOOKUP_SOURCE_CACHE
TREE_OPTIMIZER_SUBFOLDER
No protected methods found
$config
N/A
checkReloadSchedule()
callFailureCallback()
getDataFromFile()
loadDataFromCache()
loadCachedTreeRoot()
postLoadDataInitialization()
getPropertiesFromHeaders()
extractLanguageProperties()
getAcceptLanguage()
getPropertiesFromIdentifier()
detectProperties()
extractClientSideInputs()
normaliseHeaders()
checkIsDataLoaded()
cachePut()
cacheGet()
$ACCEPT_LANGUAGE_HEADER
$deviceData
$componentDetector
$propertiesCollector
$propertyMappingsRunner
$cacheService
$cacheEnabled
$httpInputSanitiser
$clientSideParser
$cacheRootJsonFilePath
$optimizerTempDir
N/A

Constants

API_ID

API_ID = 1

API_VERSION

API_VERSION = '3.2'

MIN_PHP_VERSION

MIN_PHP_VERSION = '7.0'

XMSG_PROBLEM_READING_FROM_STRING

XMSG_PROBLEM_READING_FROM_STRING = "Problem reading JSON data from string."

XMSG_FILE_NOT_FOUND

XMSG_FILE_NOT_FOUND = 'Unable to read "%s" file, make sure file exists and has read permissions.'

XMSG_MISSING_DATA

XMSG_MISSING_DATA = "The device instance failed to initialize: data file should be loaded first"

LOOKUP_SOURCE_TREE

LOOKUP_SOURCE_TREE = 'tree'

LOOKUP_SOURCE_CACHE

LOOKUP_SOURCE_CACHE = 'cache'

TREE_OPTIMIZER_SUBFOLDER

TREE_OPTIMIZER_SUBFOLDER = 'DeviceAtlas_DeviceApi'

Properties

$config

$config : 

Type

$ACCEPT_LANGUAGE_HEADER

$ACCEPT_LANGUAGE_HEADER : 

Type

$deviceData

$deviceData : 

Type

$componentDetector

$componentDetector : 

Type

$propertiesCollector

$propertiesCollector : 

Type

$propertyMappingsRunner

$propertyMappingsRunner : 

Type

$cacheService

$cacheService : 

Type

$cacheEnabled

$cacheEnabled : 

Type

$httpInputSanitiser

$httpInputSanitiser : 

Type

$clientSideParser

$clientSideParser : 

Type

$cacheRootJsonFilePath

$cacheRootJsonFilePath : 

Type

$optimizerTempDir

$optimizerTempDir : 

Type

Methods

buildDataFile()

buildDataFile(  $dataFileDownloadUrl) 

Parameters

$dataFileDownloadUrl
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

loadDataFromFile()

loadDataFromFile(string  $jsonDataFilePath, boolean  $refreshCache = false) 

Load the DeviceAtlas device detection data into the API from a JSON file.

The JSON data file is provided by the DeviceAtlas website.

Parameters

string $jsonDataFilePath

Path to the JSON file

boolean $refreshCache

Forces the Tree Optimizer to re-build its cache (DeviceApiWeb interface)

Throws

\DeviceAtlas\Exception\DataLoadingException

downloadAndLoadDataFileFromUrl()

downloadAndLoadDataFileFromUrl(  $dataFile,   $dataFileManager = null) 

Load the DeviceAtlas data file data from a URL.

Schedule a reload if data file is stale. Re-download data file if local data file is corrupted.

Parameters

$dataFile
$dataFileManager

Throws

\DeviceAtlas\Exception\DataLoadingException

when there is a problem downloading or loading the data file.

scheduleReloadAndFinishRequest()

scheduleReloadAndFinishRequest(  $dataFile,   $dataFileManager) 

A secondary register_shutdown_call to make sure the reload method is called as the last one.

Parameters

$dataFile
$dataFileManager
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

reload()

reload(  $dataFile,   $dataFileManager,   $isScheduled = false) 

Downloads a new data file if the existing one is stale.

Loads data file into API.

Parameters

$dataFile
$dataFileManager
$isScheduled
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

__construct()

__construct(\DeviceAtlas\Device\Config|null  $config = null) 

Constructs a DeviceApi instance with default or custom config.

Parameters

\DeviceAtlas\Device\Config|null $config

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

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

loadDataFromString()

loadDataFromString(string  $data) 

Load the DeviceAtlas device detection data into the API from a string.

The JSON data file is provided by the DeviceAtlas website.

Parameters

string $data

DeviceAtlas device data

Throws

\DeviceAtlas\Exception\DataLoadingException

saveDataToCache()

saveDataToCache(  $jsonDataFilePath) 

Parameters

$jsonDataFilePath
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

getPropertyNames()

getPropertyNames() : array

Get a set of all possible property names. Note that the client side properties are not included in this set.

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

Returns

array —

A set of all possible device property names as PropertyName objects.

getApiVersion()

getApiVersion() : string

The version of this API.

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

Returns

string —

DeviceApi version

getDataVersion()

getDataVersion() : string

The version of the data file.

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

Returns

string —

The device data file version.

getDataCreationTimestamp()

getDataCreationTimestamp() : integer

The creation date/time of the loaded data file as a Unix timestamp.

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

Returns

integer —

The creation date/time of this data file as a Unix timestamp.

getDataCreationIso8601()

getDataCreationIso8601() : string

The creation date/time of the loaded data file in ISO 8601 format.

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

Returns

string —

The creation date/time of the loaded data file in ISO 8601 format.

getProperties()

getProperties(string|array  $identifierOrHeaders,   $clientSideString = null) : \DeviceAtlas\Properties

Get the properties for an identifier merged with the client side properties (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 override any properties discovered from the main JSON data file.

Parameters

string|array $identifierOrHeaders

An identifier such as a User-Agent or Client Hints model, or map of HTTP headers.

$clientSideString

Throws

\DeviceAtlas\Device\ClientPropertiesException

Returns

\DeviceAtlas\Properties

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

downloadAndLoadDataFile()

downloadAndLoadDataFile(  $dataFileDownloadUrl) 

Parameters

$dataFileDownloadUrl
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

checkReloadSchedule()

checkReloadSchedule(  $dataFile,   $dataFileManager,   $forceReload = false) 

Parameters

$dataFile
$dataFileManager
$forceReload
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

callFailureCallback()

callFailureCallback(\Exception  $ex,   $dataFile) 

Call user defined callback if set.

Parameters

\Exception $ex
$dataFile
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

getDataFromFile()

getDataFromFile(  $jsonDataFilePath) 

Parameters

$jsonDataFilePath
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

loadDataFromCache()

loadDataFromCache(  $jsonDataFilePath,   $refreshCache = false) 

Parameters

$jsonDataFilePath
$refreshCache
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

loadCachedTreeRoot()

loadCachedTreeRoot() 

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

postLoadDataInitialization()

postLoadDataInitialization() 

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

getPropertiesFromHeaders()

getPropertiesFromHeaders(  $headers,   $clientSideString = null) 

Parameters

$headers
$clientSideString
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

extractLanguageProperties()

extractLanguageProperties(  $properties,   $acceptLanguageHeader) 

Parameters

$properties
$acceptLanguageHeader
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

getAcceptLanguage()

getAcceptLanguage(  $normalisedHeaders) 

Parameters

$normalisedHeaders
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

getPropertiesFromIdentifier()

getPropertiesFromIdentifier(string  $identifier,   $clientSideString = null) : \DeviceAtlas\Properties

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.

Parameters

string $identifier

The User-Agent string

$clientSideString

Throws

\DeviceAtlas\Device\ClientPropertiesException

Returns

\DeviceAtlas\Properties

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

detectProperties()

detectProperties(  $normalisedHeaders,   $clientSideString = null) 

Parameters

$normalisedHeaders
$clientSideString
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

extractClientSideInputs()

extractClientSideInputs(  $dynamicProperties,   $normalisedHeaders) 

The client side string may contain identifiers that can be used for component detection. This method adds these identifiers to the headers map.

Parameters

$dynamicProperties
$normalisedHeaders
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

normaliseHeaders()

normaliseHeaders(  $headers) 

Performs the following on header keys: lowercase, replaces "_" with "-" and strips prefixed "http-" if present.

Parameters

$headers
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

checkIsDataLoaded()

checkIsDataLoaded() 

Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

cachePut()

cachePut(  $identifierOrHeaders,   $clientSideString,   $properties,   $acceptLanguage = null) 

Parameters

$identifierOrHeaders
$clientSideString
$properties
$acceptLanguage
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275

cacheGet()

cacheGet(  $identifierOrHeaders,   $clientSideString,   $acceptLanguage = null) 

Parameters

$identifierOrHeaders
$clientSideString
$acceptLanguage
Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275 Warning: count(): Parameter must be an array or an object that implements Countable in /opt/phpdoc/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275