Using WURFL in PHP Applications with the Database API

 

Requirements

• PHP 5.1+
• Web Server (the following have been tested):
  • Apache
  • lighttpd
  • NGINX with FastCGI
  • IIS
  • HipHop for PHP (must use MySQL 5 with the PDO DB Connector)
• Database (one of the following)
  • MySQL 4 (MySQL4 DB Connector)
  • MySQL 5 (MySQL5 or PDO DB Connector)
  • MongoDB (MongoDB DB Connector)
  • Microsoft SQL Server 2005+ (MSSQL2005 DB Connector)
  Note: for MySQL (4 or 5), the PHP MySQLi extension is required.

Installation

Download the WURFL Database API package and unpack it in any directory that your PHP-enabled web server can access.

Configuration File

Copy the file TeraWurflConfig.php.example to TeraWurflConfig.php, then edit it. Each setting is described in detail in the comments. The only thing you NEED to modify is the database info (user, pass, db, etc) NOTE: By default, the Database API is configured to use MySQL 5.x. If you are using a different database, set the DatabaseConnector accordingly (see Requirements above).

File Permissions

By default, the DATADIR is set to "data/". This directory holds the wurfl.xml file, your patch file(s) and the log file. This directory and EVERYTHING in it needs to be accessible (read+write) by the user that runs your webserver. This is normally "apache", "www-data" or "nobody" in Linux.

You can test the configuration by visiting the admin/install.php file in your web browser.

Database Configuration

The Database API supports MySQL (default), MSSQL 2005+ and MongoDB. Since MongoDB does not require any specific configuration, the following instructions only apply to MySQL and can be easily translated to MSSQL.

• Create a new database and a user that has a minimum of the following privileges on the new database:
  
  • SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, CREATE TMP TABLE,
        CREATE ROUTINE, ALTER ROUTINE, EXECUTE
• In the config file, set the DB_HOST, DB_USER, DB_PASS and DB_SCHEMA to the values that you set when you created the database and user.
• Verify that the database errors on the installation page are fixed by refreshing the browser. If the database tables don't exist yet they will be created for you when you load the WURFL file in the next step.

You should not see any problems on the installation page:

 

Loading the WURFL Database

• If you are a commercial licensee, go to your account at ScientiaMobile.com and copy your Direct Download URL, then paste it in your config file in the WURFL_DL_URL property:
  

  /**
  * URL of WURFL File.  If you have a ScientiaMobile license, use the Direct Download URL from your account.
  * @var String
  */
  public static $WURFL_DL_URL = "http://www.scientiamobile.com/wurfl/xxxxxx/wurfl.zip";

• Once you've completed all the steps on the installation page, you can load the database with the WURFL data. There are three sources that the data can come from:
  1. Your local WURFL file: This will load the DATADIR/wurfl.xml file into your database.
  2. The current released WURFL: This will download the current wurfl.xml file from your ScientiaMobile account and load it into your database.
          Note: this option is only available if you are a commercial licensee and have updated the config with your Direct Download URL.
• There will be a delay while the server loads/downloads the WURFL, then you should see something like this:

Database Update OK

Total Time: 10.211848974228
Parse Time: 0.43991899490356
Validate Time: 2.7456870079041
Sort Time: 1.3005568981171
Patch Time: 0.44084501266479
Database Time: 3.9245390892029
Cache Rebuild Time: 1.3603019714355
Number of Queries: 294
PHP Memory Usage: 213.19 MB
--------------------------------
WURFL Version: www.wurflpro.com - 2009-08-25 08:15:48 (Tue Aug 25 08:19:41 -0500 2009)
WURFL Devices: 13714
PATCH New Devices: 3036
PATCH Merged Devices: 2

Update Complete!

If there are errors, they are most likely permission problems trying to write the temporary downloaded file to the DATADIR directory. Also, some users have reported a "memory allocation" error - to fix this increase OVERRIDE_MEMORY_LIMIT in the config file. If there are no errors, click on "Return to administration tool".

Using the WURFL API

Let's take a look at how you can use the API in your applications. Here's an example of serving different content to different classes of devices:

<?php
// Include the main class file
require_once('./TeraWurfl.php');
 
// instantiate a new TeraWurfl object
$wurflObj = new TeraWurfl();
 
// Get the capabilities of the current client.
$wurflObj->getDeviceCapabilitiesFromRequest();

$is_wireless = $wurflObj->getDeviceCapability('is_wireless_device');
$is_smarttv = $wurflObj->getDeviceCapability('is_smarttv');
$is_tablet = $wurflObj->getDeviceCapability('is_tablet');
$is_phone = $wurflObj->getDeviceCapability('can_assign_phone_number');
$is_mobile_device = ($is_wireless || $is_tablet);

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";
	}
}
?>

You can also check individual User Agents like this:

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

Summary

The WURFL Database 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.