WURFL in PHP

Posted byProsoxi.com Webmaster Leave a comment on WURFL in PHP

First, make sure you have PHP 5.1.0 or greater installed. The PHP API is used in production on UNIX, Linux and Windows servers in Apache, lighttpd, NGINX

with FastCGI, IIS and HipHop for PHP, although it should run in any environment that supports PHP 5.1.

  • Download the new WURFL API package.
  • Unpack it in any directory that your PHP-enabled web server can access.
Configuration

There is a usage example included with the PHP API in the examples/demo folder. The file examples/demo/index.php demonstrates how you can use the API to display the capabilities of a visiting device. The include_once statement in the beginning of the file is used to load the configuration script:

 

include_once './inc/wurfl_config_standard.php';

That script is used to initialize the WURFL PHP API and detect the visiting device. By default, the demo uses standard PHP classes for configuration (previously XML files were default). If you prefer to use the XML configuration, please include ./inc/wurfl_config_xml.php instead.

Here is the default configuration file (shortened for brevity):

 

$wurflDir = dirname(__FILE__) . '/../../../WURFL';

$resourcesDir = dirname(__FILE__) . '/../../resources';

require_once $wurflDir.'/Application.php';

$persistenceDir = $resourcesDir.'/storage/persistence';

$cacheDir = $resourcesDir.'/storage/cache';

// Create WURFL Configuration

$wurflConfig = new WURFL_Configuration_InMemoryConfig();

// Set location of the WURFL File

$wurflConfig->wurflFile($resourcesDir.'/wurfl.zip');

// Set the match mode for the API ('performance' or 'accuracy')

$wurflConfig->matchMode('performance');

// Setup WURFL Persistence

$wurflConfig->persistence('file', array('dir' => $persistenceDir));

// Setup Caching

$wurflConfig->cache('file', array('dir' => $cacheDir, 'expiration' => 36000));

// Create a WURFL Manager Factory from the WURFL Configuration

$wurflManagerFactory = new WURFL_WURFLManagerFactory($wurflConfig);

// Create a WURFL Manager

/* @var $wurflManager WURFL_WURFLManager */

$wurflManager = $wurflManagerFactory->create();

You can see from the configuration that the name of the WURFL File, the Match Mode and the Persistence and Caching options are set, then a WURFL Manager is created, which will be used to query for device capabilities.

What does this stuff mean?
  • WURFL File: this XML file (zipped by default) contains the raw device information that is used by the API.
  • Match Mode: There are two modes: performance and accuracy. The main difference is in the way that desktop web browsers are detected. In performance mode, most desktop web browsers will be detected as a generic web browser, and no attempt will be made to further identify them.
  • Persistence: The WURFL data is stored in the Persistence Provider. The recommended setting for this is file (filesystem-based storage).
  • Cache: The cache is used to store user agents that are detected by the API. If this is set to memcache or apc, it will also be used to cache data that would normally come from the Persistence provider.

Since the default configuration uses the file system for both Persistence and Caching, you’ll need to make sure your webserver can write to theresources/storage/persistence and resources/storage/cache directories.

If you’ve used WURFL in the past, you may have noticed something missing: web_browsers_patch.xml. As of WURFL 2.3.1, there is no need to include the web patch, as it has been merged into the main WURFL file.

Initialization

At this point, the persistence directory is empty. The first time you attempt to use the API, it will automatically build the persistence data for you. To do this, open a web browser and go to the examples/demo/ directory, for example, if you installed the PHP API in a folder called /wurfl-php-api in your local machine’s web document root, you would visit http://localhost/wurfl-php-api/examples/demo/. Your browser will pause for a while, while your disk becomes busy with a lot of activity. The new API is building the persistence data on disk to make sure that your future WURFL queries are very fast.
After a 10-30 seconds or so, you will see something like this:

php_example

Notice that Google Chrome 18 was detected as generic_web_browser because we’re in high-performance mode. If you want to detect web browsers accurately, you’ll need to change your Match Mode to accuracy.

Now your server is setup to and ready to use the WURFL PHP API for mobile device detection.

Using the WURFL API

Let’s take a look at how you can use the API in your applications. If you haven’t already done so, take a look at the code example in the Configuration section above. The example shows how to create a WURFL_WURFLManager object – this will be used to get the visiting device’s capabilities.

Next, we need to detect the visiting device. Typically, the WURFL API is used on a webserver to detect the capabilities of visiting devices. In this scenario, the following method should be used:

 

$requestingDevice = $wurflManager->getDeviceForHttpRequest($_SERVER);

If you want to query the API for a user agent manually, you can use this method:

 

$user_agent = "Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0; IEMobile/9.0; NOKIA; Lumia 800)";

$requestingDevice = $wurflManager->getDeviceForUserAgent($user_agent);

Now you’ve got the $requestingDevice itself (type WURFL_CustomDevice) and you can ask it for specific device capabilities.

Note that in the PHP API (unlike the Database API), all capability values are strings, so you will need to compare them to strings, like this:

 

if ($requestingDevice->getCapability('is_tablet') == 'true') {

echo "Tablet";

}

Here’s an example that outputs a different message based on the device type (Phone, Tablet, Smart TV, Web Browser, etc):

 

$is_wireless = ($requestingDevice->getCapability('is_wireless_device') == 'true');

$is_smarttv = ($requestingDevice->getCapability('is_smarttv') == 'true');

$is_tablet = ($requestingDevice->getCapability('is_tablet') == 'true');

$is_phone = ($requestingDevice->getCapability('can_assign_phone_number') == 'true');

$is_mobile_device = ($iswireless || $istablet);

if (!$is_mobile_device) {

if ($is_smarttv) {

echo "This is a Smart TV";

} else {

echo "This is a Desktop Web Browser";

}

} else {

if ($is_tablet) {

echo "This is a Tablet";

} else if ($is_phone) {

echo "This is a Mobile Phone";

} else {

echo "This is a Mobile Device";

}

}

Summary

The WURFL PHP API is a highly-flexible and high-performance mobile device detection API that makes it easy for you to make server-side decisions based on your website visitor’s devices in order to present them with a user experience that is appropriate for their device.

Leave a comment