• About Us
  • Blog
  • Basket
  • Account
  • Sign In
  •  

PHP API

Introduction

There are two ways to access the device detection API, a self-hosted on-premise version and a cloud version accessed through calls to the 51Degrees servers.

The new 51Degrees PHP common API aims to make switch from Cloud based Device-Detection to the On-Premise version much easier for developers. It allows you to switch without the need to re-write your code by providing a common API between the two solutions connected by an interface which communicates with the core software.

Php Sessions

The common API uses PHP sessions to store information (in variables) to be used across multiple pages.

Download

You can download the PHP Common API from the Device Detection Github repository here.

Installation

Getting started is as simple as copying the contents of the common-api/51Degrees directory into your webservers document root.

# For apache based webservers
$ cp -R Device-Detection/php/common-api/51Degrees /var/www/html/

Configuration

Edit the config.php file within the common-api/51Degrees directory to configure the Common API. Include this file using require() in a PHP script before initialising the provider:

require("../config.php");
$provider = FiftyOneDegrees\FiftyOneDegreesGetProvider($settings);
Both cloud and on Premise

Passed in during provider initialisation.

Property Type Required Default Description
FiftyOneProvider String Mandatory None Set to Cloud/TRIE/Pattern
FiftyoneShareUsage Boolean Optional True Whether the API should send usage data.
FiftyOneLicence String See description None Not required for On-Premise as manual datafile updates can be used rather than automatic updates. Required for Cloud.
FiftyOneLogLevel String Optional Fatal Either Debug, Info, Warn or Fatal – minimum log level to log to file.
FiftyOneLogFile String Optional ./51Degrees.log Path to log file.
Cloud only

Passed in during provider initialisation, these can be left blank when using On-Premise Device-Detection.

Property Type Required Default Description
FiftyOneUseSession Boolean Optional True Whether the cloud API should store detection results in the session.
FiftyOneSessionLifetime Integer Optional None length of time to keep matches in session for.
FiftyOneProperties String Array Optional All Properties An array of which properties to fetch (if left blank all are fetched). For the On-Premise version this is set in the extension properties. For more information about available properties see the Property Dictionary.
Example configuration

The following shows an example of the contents of config.php.

$settings = array(
    "FiftyOneProvider"=>"Cloud",
    "FiftyoneShareUsage"=>true,
    "FiftyOneLicence"=>"***YOUR_LICENCE_KEY***",
    "FiftyOneLogLevel"=>"fatal",
    "FiftyOneLogFile"=>"51degrees.log",
    "FiftyOneUseSession"=>true,
    "FiftyOneSessionLifetime"=>"60",
    "FiftyOneProperties"=>array("IsMobile","HardwareVendor","PlatformName")
);

Usage

To use the 51Degrees PHP Common API, create a new session then require the common API and configuration files. Fetch the provider, this will have been initialised on server startup if you have migrated to an On-Premise extension. This object can be called to process a new match object which can return properties of the specific mathced device.

<?php
session_start();
require("../51degrees.php");
require("../config.php");
$provider = FiftyOneDegrees\FiftyOneDegreesGetProvider($settings);
$match = $provider->getMatch($_SERVER['HTTP_USER_AGENT']);
echo $match->getValue('IsMobile');
?>

Logging

The PHP common API supports logging.

This is handled by the ‘logger.php’ script

Events are logged in ‘./51degrees.log’ which is the default setting.

Make sure that the webserver user group has write access to the current working drectory or create the file '51degrees.log'. On Linux systems, set the file permissions so that the server user/group has write access.

Best practise dictates that the location for the log file should be set to '/var/log/51degrees/' this can be setting when passing parameters to the provider.