Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
common-api BUILD: Updated pre-built SWIG generated wrappers. Nov 30, 2017
examples
pattern BUILD: Updated pre-built SWIG generated wrappers. Nov 30, 2017
trie BUILD: Updated pre-built SWIG generated wrappers. Nov 30, 2017
.gitignore Initial commit Jun 27, 2017
README.md FEAT: 51Degrees PHP common API. Nov 30, 2017

README.md

51Degrees Device Detection in C PHP C extension & Common API

Supported Databases | Developer Documention | Available Properties

Need C | Java | .NET | Python | Perl | Node.js?

Introduction

In PHP, use like...

<?php
$match = $provider->getMatch($_SERVER['HTTP_USER_AGENT']);

// Access individual properties.
$isMobile = $match->getValue('IsMobile');
if ($isMobile === "True") {
	// Code for mobile device.
} else {
	// Code for Desktop.
}
echo "<p>You are using ".$match->getValue('BrowserName')." browser of version".$match->getValue('BrowserVersion').".</p>";
echo "<p>The type of your device is: ".$match->getValue('DeviceType').".</p>";
?>

Use this project to detect device properties using HTTP browser User-Agents as input. It can be used to process server web log files, or for real time device detection to support web optimisation.

Three detection methods are supported.

Pattern: Searches for device signatures in a User-Agent returning metrics about the validity of the results. Does NOT use regular expressions.

Hash Trie: A large binary Trie (pronounced Try) populated with User-Agent signatures. Very fast.

Cloud: Queries a RESTful API hosted by 51Degrees to enable device Detection.

Pattern and Hash Trie methods use an external data file which can easilly be updated.

Common API

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

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.

  • FiftyOneProvider – String – mandatory - Set to Cloud/TRIE/Pattern
  • FiftyoneShareUsage – Boolean – Optional – default True – Whether the API should send usage data.
  • FiftyOneLicence – String – Not required for On-Premise as manual datafile updates can be used rather than automatic updates. Required for Cloud. No default.
  • FiftyOneLogLevel – String – Either Debug, Info, Warn or Fatal – minimum log level to log to file. Fatal default.
  • FiftyOneLogFile – String – Path to log file. Default to current directory and 51degrees.log

Cloud only

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

  • FiftyOneUseSession – Boolean – Optional – default True – Whether the cloud API should store detection results in the session.
  • FiftyOneSessionLifetime – Integer – Optional – length of time to keep matches in session for.
  • FiftyOneProperties – String Array – Optional – 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

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

On-Premise Extensions

This section describes how to install and configure the PHP On-Premise extensions. This can either be used stand-alone or as part of the common API which is especially useful when migrating from Cloud to On-Premise Device-Detection.

Breaking Changes

The PHP API is now built from the same source as every other C based API. This means new features are introduced as soon as they are developed. It can still be used in nearly the same way but some of the namings and syntax has changed slightly. This readme will explain the usage fully.

Dependencies

  • g++
  • make
  • php5
  • php5-dev
  • git
  • Optional: SWIG 2.0 (>=3.0.13 for php7)

For Ubuntu based distributions these can be found on apt, use

$ sudo apt-get install g++ make php5 php5-dev git swig2.0

Building the SWIG generated wrappers is optional as the SWIG generated files are included for the Pattern and Hash Trie extensions, with variations for both PHP5 and PHP7. Building the SWIG wrapper for PHP7 will also require you install SWIG version >= 3.0.13. At the present time there is no stable release for SWIG which supports PHP7, however SWIG 3.0.13 or higher can be built from the SWIG source code: https://github.com/swig/swig

Install

Linux

First, clone 51Degrees/Device-Detection repository using git:

$ git clone https://github.com/51Degrees/Device-Detection.git

Choose the detection method you wish to use and navigate to the corresponding directory within the 'php' directory. For Pattern:

$ cd Device-Detection/php/pattern

For Trie:

$ cd Device-Detection/php/trie

Install by running the following commands:

For PHP 5
phpize
./configure
sudo make install
Or for PHP 7
phpize
./configure PHP7=1
sudo make install

If Rebuilding SWIG Wrappers

PHP 5
phpize
./configure SWIG=1 
sudo make install
PHP 7
phpize
./configure PHP7=1 SWIG=1 
sudo make install

The phpize command will prepare the build environment for the PHP extension. The ./configure will check your environment and prepare the makefile. Finally the make install will build the detector module and place it in the PHP extensions directory. The build script should also tell you where the extension has been placed.

Windows

First, clone 51Degrees/Device-Detection repository using git:

$ git clone https://github.com/51Degrees/Device-Detection.git

Now download the php source (the same version as is installed on the target system) from http://windows.php.net/download and extract to either the Pattern or Trie directory and rename to php-src.

Download the necessary binary tools from http://windows.php.net/downloads/php-sdk/ and extract the bin subfolder to either the Pattern or Trie directory. In a developer command prompt (for PHP 5.5/5.6 use Visual Studio 2012, for 7.0+ use 2015) and move to either the Pattern or Trie directory. make the binary tools available in the system path:

$ bin\phpsdk_setvars.bat

Configure and build the php source by running the following in the php-src directory:

$ cd php-sdk
$ buildconf
$ configure --disable-all --enable-cli
$ nmake

The VisualStudio directory contains a project which can now be opened and built. This will then build the dll in the VisualStudio\Release directory.

Just include the dll in a suitable PHP directory and configure as below.

Configure

Before using the extension you must supply the PHP environment with information on the location of the module and the module parameters. This should be done by editing your PHP.ini file.

If you are not sure where the PHP.ini file is located on your system you can create a .php page and place in your server directory. Add the following php code to the page

<?php
phpinfo();
?>

and look for the 'php.ini' file location.

Open the 'php.ini' file and add the following to the bottom. Please note that superuser privileges will most likely be required to edit the file.

The first is the location of the extension binary (note that your location may be different from the one here. Check for the location). The second is the is the path to the 51Degrees data file. Third parameter defines the number of WorkSet items in the pool. Make sure that it is in a location that Apache has read permissions over.

extension=/usr/lib/php5/FiftyOneDegreesPatternV3.so
FiftyOneDegreesPatternV3.data_file=path/to/51Degrees/data/file.dat
FiftyOneDegreesPatternV3.property_list=BrowserName,BrowserVendor,BrowserVersion,DeviceType,HardwareVendor,IsTablet,IsMobile,IsCrawler,ScreenInchesDiagonal,ScreenPixelsWidth
FiftyOneDegreesPatternV3.cache_size=10000
FiftyOneDegreesPatternV3.pool_size=20

In both Pattern and Trie directories, there is a php file which contains all the classes needed. When running the extensions stand-alone, put this in a directory accessible by your web server, e.g. /var/www/html/51Degrees. This can then be included at the top of any php script using the detector with

require(path/to/FiftyOneDegreesPatternV3.php);

or

require(path/to/FiftyOneDegreesTrieV3.php);

Common Settings

extension

This setting tells the PHP environment where the compiled extension is located.

Pattern settings

These settings should only be used with Pattern flavour of the extension.

FiftyOneDegreesPatternV3.data_file

This setting tells the extension where the 51Degrees Pattern data file is located. Pattern data files have the '.dat' file extension. Make sure the file is uncompressed and is accessible by your PHP environment.

FiftyOneDegreesPatternV3.property_list

This is essentially a list of properties you wish the dataset to be initialized with. Premium data file provides over 130 properties and Enterprise over 160 properties. This setting allows you to only choose properties you are interested in. Leaving this setting line empty or not including it at all will return a full list of properties in detection results.

FiftyOneDegreesPatternV3.cache_size

This setting tells the detector how many elements should be cached. Cache helps to speed up device detection by keeping a list of the most frequently encountered devices in memory, hence reducing the amount of requests to the device data.

FiftyOneDegreesPatternV3.pool_size

This setting tells the detector how many worksets the detector should use. Worksets are used to keep the information associated with the request and detection results. A workset is drawn from the pool when a request commences and is released back to the pool upon request end.

Trie Settings

FiftyOneDegreesTrieV3.data_file

This setting tells the extension where the 51Degrees Trie data file is located. Pattern data files have the '.trie' file extension. Make sure the file is uncompressed and is accessible by your PHP environment.

FiftyOneDegreesTrieV3.property_list

This is essentially a list of properties you wish the dataset to be initialized with. Premium data file provides over 130 properties and Enterprise over 160 properties. This setting allows you to only choose properties you are interested in. Leaving this setting line empty or not including it at all will return a full list of properties in detection results.

Usage

To use the 51Degrees extension, start by fetching the provider that will have been initialised on server startup. Then this object can be called to process a new match object which can return properties of the specific matched device. This can be seen in the code below:

<?php
require("FiftyOneDegreesPatternV3");
$provider = FiftyOneDegreesPatternV3::provider_get();
$match = $provider->getMatch($_SERVER['HTTP_USER_AGENT']);
echo $match->getValue('IsMobile');
?>

Examples

In the examples folder, you can find examples of various functionalities that the 51Degrees detector has such as:

  • Matching with a User-Agent
  • Matching with a device id
  • Evaluating match metrics
  • Offline processing
  • Strongly typed variables
  • Finding profiles

A full explanation of these can be found within the files or at PHP Tutorials.

You can find an example PHP page within the Device-Detection/php/examples directory called example.php. It demonstrates the output of each of the above function presented in a neat form that lists HTTP headers and provides useful links.

To use these examples, first make sure that all settings (see Configuration for Pattern/Trie settings) are set in /etc/php5/cli/php.ini and the enable_dl line reads enable_dl=On. Then run

php -S localhost:8080

in the eamples directory to run start a server (only available in php 5.4+), and all examples will be available in a browser at, for example, localhost:8080/example.php. Or any of the other files in that directory.

You can’t perform that action at this time.