Mobi_Mtld_DA_Device_DeviceApiWeb
extends Mobi_Mtld_DA_Device_DeviceApi
in package
A small extension to the core DeviceApi that uses the request HTTP headers for detection and property lookup.<br/><br/>
When detecting user's device as real-time on a website it is strongly recommend
to use the DeviceApiWeb library and getProperties as shown bellow.
The getProperties of DeviceApiWeb, automatically detects the availability
of the client-side properties and will use them for detection. If you want
to have a more accurate detection (specially for apple devices) or have the
client side properties included in the property sets, simply include the
DeviceAtlas client-side component JavaScript library in the pages.
The API may be configured configured to improve performance and memory footprint,
when used in a web application for real-time device detection:
- Optimizing the data file.
- Caching the results.
The getProperties() method in this class extracts the most suitable headers
from the request headers.
Example usage:
// require_once "/PATH/TO/Mobi/Mtld/DeviceApiWeb.php";
// default=the data optimization is on
$deviceApi = new Mobi_Mtld_DA_Device_DeviceApiWeb();
try {
$deviceApi->loadDataFromFile("/path/to/datafile.json");
// get all properties from the current request
$properties = $deviceApi->getProperties();
// .... use the properties ....
if ($properties->contains("mobileDevice", true)) {
if ($properties->containsKey("model")) {
$deviceModel = $properties->model;
}
}
} catch (...
Tags
Table of Contents
- API_VERSION = 'DEVICEATLAS_API_VERSION'
- Api version.
- LOOKUP_SOURCE_CACHE = 'cache'
- LOOKUP_SOURCE_OPTIMIZED_TREE = 'optimized tree'
- LOOKUP_SOURCE_TREE = 'tree'
- MIN_PHP_VERSION = '5.2.3'
- Minimum PHP version required for this API to run. *
- $config : mixed
- $LANGUAGE_HEADER : mixed
- $tree : mixed
- $treeCached : mixed
- $PROPERTY_NAME_LANGUAGE : mixed
- $PROPERTY_NAME_LANGUAGE_LOCALE : mixed
- __construct() : mixed
- Constructs a DeviceApiWeb instance with custom configs.
- buildDataFile() : mixed
- downloadAndLoadDataFile() : mixed
- downloadAndLoadDataFileFromUrl() : mixed
- Load the DeviceAtlas data file data from a URL.
- getApiVersion() : string
- Get DeviceApi version.
- getDataCreationTimestamp() : string
- Get the device data creation (JSON file) timestamp.
- getDataRevision() : int
- Get the device data generation revision.
- getDataVersion() : string
- Get the device data (JSON file) version.
- getDeviceAtlasApiVersion() : mixed
- getLookupSource() : string
- Get the source properties fetch source to be used for debugging.
- getProperties() : The
- Get the Device properties for the current request. The most suitable request headers are extracted and used for detection and property lookup.<br/> If the client-side-component has been used and the client-side properties exists in the client-side cookie, then the properties will be included.<br/> You can change the API's configs using class "Mobi_Mtld_DA_Device_Config".
- getPropertiesFromUa() : Mobi_Mtld_DA_Properties
- Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component).
- getPropertyNames() : array<string|int, mixed>
- Get a set of available device property names.
- getTreeCache() : mixed
- loadDataFromFile() : mixed
- loadDataFromString() : mixed
- Load the DeviceAtlas device detection data into the API from a string.
- loadTreeFromJsonFilePath() : mixed
- reload() : mixed
- Downloads a new data file if the existing one is stale.
- scheduleReloadAndFinishRequest() : mixed
- A secondary register_shutdown_call to make sure the reload method is called as the last one; when available call fastcgi_finish_request() too, to make sure there is no delay for a visitor/client.
- setConfig() : mixed
- Set new config settings via a new Config object and drop current cache.
- setTreeCache() : mixed
- addLanguageProperties() : mixed
- Get the Accept-Language header and add language properties to the property list
- callFailureCallback() : mixed
- Call user defined callback if set.
- checkReloadSchedule() : mixed
- getPropertyTypeAsByte() : mixed
- Convert tree property types to interface data types
- normaliseKeys() : mixed
- Normalise the HTTP header keys, replaces "_" with "-" and removes any HTTP_ prefix
Constants
API_VERSION
Api version.
public
mixed
API_VERSION
= 'DEVICEATLAS_API_VERSION'
LOOKUP_SOURCE_CACHE
public
mixed
LOOKUP_SOURCE_CACHE
= 'cache'
LOOKUP_SOURCE_OPTIMIZED_TREE
public
mixed
LOOKUP_SOURCE_OPTIMIZED_TREE
= 'optimized tree'
LOOKUP_SOURCE_TREE
public
mixed
LOOKUP_SOURCE_TREE
= 'tree'
MIN_PHP_VERSION
Minimum PHP version required for this API to run. *
public
mixed
MIN_PHP_VERSION
= '5.2.3'
Properties
$config
protected
mixed
$config
$LANGUAGE_HEADER
protected
static mixed
$LANGUAGE_HEADER
= 'accept-language'
$tree
protected
mixed
$tree
$treeCached
protected
mixed
$treeCached
$PROPERTY_NAME_LANGUAGE
private
static mixed
$PROPERTY_NAME_LANGUAGE
= 'language'
$PROPERTY_NAME_LANGUAGE_LOCALE
private
static mixed
$PROPERTY_NAME_LANGUAGE_LOCALE
= 'languageLocale'
Methods
__construct()
Constructs a DeviceApiWeb instance with custom configs.
public
__construct([Mobi_Mtld_DA_Device_Config $config = null ]) : mixed
Parameters
- $config : Mobi_Mtld_DA_Device_Config = null
Tags
Return values
mixed —buildDataFile()
public
abstract buildDataFile(mixed $dataFileDownloadUrl) : mixed
Parameters
- $dataFileDownloadUrl : mixed
Return values
mixed —downloadAndLoadDataFile()
public
downloadAndLoadDataFile(mixed $dataFileDownloadUrl) : mixed
Parameters
- $dataFileDownloadUrl : mixed
Return values
mixed —downloadAndLoadDataFileFromUrl()
Load the DeviceAtlas data file data from a URL.
public
downloadAndLoadDataFileFromUrl(mixed $dataFile[, mixed $dataFileManager = null ]) : mixed
Schedule a reload if data file is stale. Re-download data file if local data file is corrupted.
Parameters
- $dataFile : mixed
- $dataFileManager : mixed = null
Tags
Return values
mixed —getApiVersion()
Get DeviceApi version.
public
static getApiVersion() : string
Return values
string —DeviceApi version
getDataCreationTimestamp()
Get the device data creation (JSON file) timestamp.
public
getDataCreationTimestamp() : string
Return values
string —The string data creation timestamp
getDataRevision()
Get the device data generation revision.
public
getDataRevision() : int
Return values
int —Data generation revision
getDataVersion()
Get the device data (JSON file) version.
public
getDataVersion() : string
Return values
string —The data version
getDeviceAtlasApiVersion()
public
getDeviceAtlasApiVersion() : mixed
Return values
mixed —getLookupSource()
Get the source properties fetch source to be used for debugging.
public
getLookupSource() : string
Return values
string —The value of one this constants: LOOKUP_SOURCE_TREE or LOOKUP_SOURCE_OPTIMIZED_TREE or LOOKUP_SOURCE_CACHE
getProperties()
Get the Device properties for the current request. The most suitable request headers are extracted and used for detection and property lookup.<br/> If the client-side-component has been used and the client-side properties exists in the client-side cookie, then the properties will be included.<br/> You can change the API's configs using class "Mobi_Mtld_DA_Device_Config".
public
getProperties([mixed $headers = null ][, mixed $clientSideProperties = null ]) : The
Depending on the configs the properties may include user-agent dynamic properties and language/locale properties.
Parameters
- $headers : mixed = null
- $clientSideProperties : mixed = null
Tags
Return values
The —found properties
getPropertiesFromUa()
Get the properties for a User-Agent merged with the client-side properties (when provided by the DeviceAtlas client side component).
public
getPropertiesFromUa(mixed $userAgent[, mixed $clientSideProperties = null ]) : Mobi_Mtld_DA_Properties
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
- $userAgent : mixed
- $clientSideProperties : mixed = null
Tags
Return values
Mobi_Mtld_DA_Properties —A set of properties (Property objects) wrapped in a Properties object
getPropertyNames()
Get a set of available device property names.
public
getPropertyNames() : array<string|int, mixed>
Return values
array<string|int, mixed> —A set of available device property names as PropertyName objects. A PropertyName object holds a property-name and it's data-type
getTreeCache()
public
getTreeCache() : mixed
Return values
mixed —loadDataFromFile()
public
abstract loadDataFromFile(mixed $jsonDataFilePath) : mixed
Parameters
- $jsonDataFilePath : mixed
Return values
mixed —loadDataFromString()
Load the DeviceAtlas device detection data into the API from a string.
public
loadDataFromString(mixed $data) : mixed
The JSON data file is provided by the DeviceAtlas web-site.
Parameters
- $data : mixed
Tags
Return values
mixed —loadTreeFromJsonFilePath()
public
loadTreeFromJsonFilePath(mixed $jsonDataFilePath) : mixed
Parameters
- $jsonDataFilePath : mixed
Return values
mixed —reload()
Downloads a new data file if the existing one is stale.
public
reload( $dataFile, $dataFileManager) : mixed
Loads data file into API.
Parameters
Return values
mixed —scheduleReloadAndFinishRequest()
A secondary register_shutdown_call to make sure the reload method is called as the last one; when available call fastcgi_finish_request() too, to make sure there is no delay for a visitor/client.
public
scheduleReloadAndFinishRequest( $dataFile, $dataFileManager) : mixed
Parameters
Return values
mixed —setConfig()
Set new config settings via a new Config object and drop current cache.
public
setConfig([Mobi_Mtld_DA_Device_Config $config = null ]) : mixed
Parameters
- $config : Mobi_Mtld_DA_Device_Config = null
Return values
mixed —setTreeCache()
public
setTreeCache(mixed $treeCached) : mixed
Parameters
- $treeCached : mixed
Return values
mixed —addLanguageProperties()
Get the Accept-Language header and add language properties to the property list
private
addLanguageProperties(mixed $acceptLanguage, mixed &$treeProperties) : mixed
Parameters
- $acceptLanguage : mixed
- $treeProperties : mixed
Return values
mixed —callFailureCallback()
Call user defined callback if set.
private
callFailureCallback(Exception $ex, $dataFile) : mixed
Parameters
Return values
mixed —checkReloadSchedule()
private
checkReloadSchedule(mixed $dataFile, mixed $dataFileManager[, mixed $forceReload = false ]) : mixed
Parameters
- $dataFile : mixed
- $dataFileManager : mixed
- $forceReload : mixed = false
Return values
mixed —getPropertyTypeAsByte()
Convert tree property types to interface data types
private
static getPropertyTypeAsByte(mixed $typeChar) : mixed
Parameters
- $typeChar : mixed
Return values
mixed —normaliseKeys()
Normalise the HTTP header keys, replaces "_" with "-" and removes any HTTP_ prefix
private
static normaliseKeys(mixed $keyVals) : mixed
Parameters
- $keyVals : mixed