Using WURFL in PHP Applications


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.

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 showing all common options:

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

// Automatically reload the WURFL data if it changes
$wurflConfig->allowReload(true);

// Optionally specify which capabilities should be loaded
$wurflConfig->capabilityFilter(array(
        "device_os",
        "device_os_version",
        "is_tablet",
        "is_wireless_device",
        "mobile_browser",
        "mobile_browser_version",
        "pointing_method",
        "preferred_markup",
        "resolution_height",
        "resolution_width",
        "ux_full_desktop",
        "xhtml_support_level",
));

// 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?

Since the default configuration uses the file system for both Persistence and Caching, you'll need to make sure your webserver can write to the resources/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.

Capability Filtering

In order to reduce memory usage and increase performance, you can specify a subset of the 500+ WURFL capabilities. You can set the desired capabilities with the $config->capabilityFilter() method:

$wurflConfig->capabilityFilter(array(
		"device_os",
		"device_os_version",
		"is_tablet",
		"is_wireless_device",
		"mobile_browser",
		"mobile_browser_version",
		"pointing_method",
		"preferred_markup",
		"resolution_height",
		"resolution_width",
		"ux_full_desktop",
		"xhtml_support_level",
));

Now, reload the WURFL file and only the capabilities you've specified will be loaded. Note that because of the virtual capability system, those capabilities listed above are always loaded, even if they are not specified. Note that the auto-reload system will not detect the change in your configuration and reload the WURFL data automatically, so you will need to either touch the WURFL file or delete your persistence folder.

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:


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

if (!$is_wireless) {
 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";
 }
}
Virtual Capabilities

Virtual capabilities are a new important feature of the WURFL API to obtain values related to the requesting agent out of the HTTP reuqest as a whole (as opposed to limiting itself to capabilities that are found in WURFL).
In order to compute its final returned value, a virtual capability may look at regular (non-virtual) capabilities as well as other parameters that can be derived from the HTTP request at run-time. Virtual capabilities are useful to model aspects of the HTTP Client that are not easily captured through the finite number of agent profiles in WURFL.
Virtual capabilities depend on certain real capabilities, which, for this reason, may be considered mandatory. These capabilities are: device_os, device_os_version, is_tablet, is_wireless_device, mobile_browser, mobile_browser_version, pointing_method, preferred_markup, resolution_height, resolution_width, ux_full_desktop, xhtml_support_level.

To get the value of a virtual capability, use the WURFL_CustomDevice::getVirtualCapability() method:

$is_smartphone = $requestingDevice->getCapability('is_smartphone');

Here is the list of virtual capabilities introduced with API 1.5:

Virtual Capability Description
is_android True if the device runs Android (any version).
is_ios True if the device runs iOS (any version).
is_windows_phone True if the device runs Windows Phone 6.5 or higher. Note that this does not include Windows Mobile or Windows CE.
is_app True if the requests is from a native app. This typically of requests from WebView components and RESTful API calls.
is_full_desktop True if the requesting device has a full desktop experience. This capability is an alias for ux_full_desktop.
is_largescreen True if the requesting device's screen is of a high resolution (over 480 pixels in width and height)
is_mobile True if the device is mobile, like a phone, tablet, media player, portable game console, etc. This capability is an alias for is_wireless_device.
is_robot True if the request is from a robot, crawler, or some other automated HTTP client.
is_smartphone True if the device is a smartphone. Internally, the matcher checks the operating system, screen width, pointing method and a few other capabilities.
is_touchscreen True if the primary pointing method is a touchscreen.
is_wml_preferred True if the requesting device should be served with WML markup.
is_xhtmlmp_preferred True if the requesting device should be served with XHTML-MP markup.
is_html_preferred True if the requesting device should be served with HTML markup.
advertised_device_os Returns the operating system name of the requesting device. This works for mobile and desktop devices. (ex: "Windows", "Mac OS X")
advertised_device_os_version Returns the operating system version of the requesting device. This works for mobile and desktop devices. (ex: "XP", "10.2.1")
advertised_browser Returns the browser name of the requesting device. This works for mobile and desktop devices. (ex: "Internet Explorer", "Chrome")
advertised_browser_version Returns the browser version of the requesting device. This works for mobile and desktop devices. (ex: "7", "29")