Introduction to WURFL

Since writing this article over 10 years ago, the device detection landscape has moved on significantly. WURFL is no longer open source and there are now additional options available to the developer, including cloud-based services that you may find easier to integrate. We recommend that readers consider DeviceAtlas or OpenDDR for their solutions.

Complying to standards is not always easy, but it is very important so that browsers will display your contents as you envisioned them and that search engines can interpret your pages correctly. The W3C started the Mobile Web Initiative in 2005. The initiative wants, among the other things, to provide a set of best practices to make sure that web developers can produce sites that are mobile friendly. I suggest that you read the recommendations from the W3C and also the “Switch On” guide, that will be helpful if you want to use a .mobi domain. Using a .mobi domain is a very easy way to make sure that your visitors will know that your site will not simply be readable on a mobile device, but that you actually applied the needed techniques to make it well suited. You don’t need a .mobi domain to develop a mobile site, but using it makes it clear to anyone that your site is mobile friendly.

Getting started with WURFL and PHP

The first thing that we should do is to be prepared to detect the browser and the device (or computer) that is visiting our site. To do this we a device information database such as DeviceAtlas or WURFL. To learn about DeviceAtlas, the world’s most comprehensive device database, please check out the DeviceAtlas website. In this article we cover the use of WURFL. In short, WURFL is a big repository of information that will help us to recognize browsers, devices and their capabilities. By capabilities we mean the ability to support certain features and standards such as image formats, mark-ups, but also the screen size, colors of the screen and so on. WURFL is an open-source project and you are not required to pay anything. In addition the project provides libraries for the most common programming languages such as Java, Python, ruby, perl. In this article we will see how it works with PHP 4.

Before we start you should download the needed files. Get the latest version of WURFL in zipped format and unzip it in a directory that you want. Download and configure the PHP library from its homepage. I suggest a basic configuration to start, add the path where you stored the wurfl.xml, leave the cache off. Make sure that the directory that you will use for the logs is writable and that the scripts have the rights to read the XML, of course.

wurfl_config.php is the file you should edit and these are the important parameters:

// Single define to be checked when starting the parser and/or the class
define(“WURFL_CONFIG”, true);
// Where all data is stored (wurfl.xml, cache file, logs, etc)
define(“DATADIR”, ‘my/path/to/data/’);
// Path and filename of wurfl_parser.php
define(“WURFL_PARSER_FILE”, ‘/my/path/to/wurfl_parser.php’);
// Path and filename of wurfl_class.php
define(“WURFL_CLASS_FILE”, ‘/my/path/to/wurfl_class.php’);
// Path and name of the wurfl
define (“WURFL_FILE”, DATADIR.”wurfl.xml”);
// Path and name of the log file
define (“WURFL_LOG_FILE”, DATADIR.”wurfl.log”);
define (“LOG_LEVEL”, LOG_INFO);
// Set this true if you want to use cache.
define (“WURFL_USE_CACHE”, false);
// Autoload set to false, I will load it when needed
define (“WURFL_AUTOLOAD”, true);
// Configure a patch file
//define(“WURFL_PATCH_FILE”, DATADIR.’wurfl_patch.xml’);
// Enable patch debug, NOT SUGGESTED for production environments
//define(“WURFL_PATCH_DEBUG”, false);

Create a start page in your document root. We will call it index.php .

If you don’t know what is the document root, or don’t know how to configure it, you might want to look at the documentation of your webserver. Apache is certainly a good choice. Make sure Apache is configured to call the PHP module and that index.php is one of the default files (DirectoryIndex directive in Apache). If not, once again, check your webserver’s manual.

Put the following lines in your start page (index.php):


$wurflObj = new wurfl_class();


echo “<pre>”;
echo “</pre>”;


This will print all the information about a Motorola c350. You don’t need to know all the capabilities in WURFL, we will just use a restricted number in this article and I will try to explain them when needed. In case you wanted to know more, you can check the WURFL site, there’s a section about all the capabilities. This example is useful to check that everything is ok. Look into your log file (as configured in wurfl_config.php) and you should see something.

WURFL is normally all about mobile devices. In our case, we want to be able to distinguish a mobile device from a desktop browser. For this reason we also need to download the “web patch“, available from the WURFL site. The “web patch” is an extension of WURFL that lists all the most common user-agents of web browsers and sets a capability that will let us know it’s not a mobile phone. To know more about the wurfl_patch file you should check the WURFL site, for the time being all you need to know is that “patch files” let you define new capabilities, override values and add new devices that are not listed, yet.

Store it in the same directory where you put wurfl.xml and change the configuration like this:

define(“WURFL_PATCH_FILE”, DATADIR.’web_browsers_patch.xml’);

Next time you will load index.php the “web patch” will be loaded and the information in it will be added.

That’s enough with downloading and configuring. Let’s go ahead with our site.

Detecting the browser

Every browser, when requesting a web page, sends its “ user-agent“, in PHP we find it in a global variable, $_SERVER[‘HTTP_USER_AGENT’]. WURFL provides us with a capability that will tell us if the requesting browser is a desktop computer or a wireless device. Notebooks and laptops are considered “desktop computers” as they run operating systems like Windows or OS X, have big screens and full keyboards. PDA’s are considered “wireless devices” as you can put them in your pocket and walk out with them.

We will now modify the previous example.

We will need a new method of the wurflObj that returns the value of the capability requested:  getDeviceCapability. The method expects a capability name as a parameter. You will get the capability value in return. Easy, isn’t it?


$wurflObj = new wurfl_class();

if ( $wurflObj->getDeviceCapability(‘is_wireless_device’) ) {
} else {


As you can see we used the PHP variable for the user agent, if you load the page with your favorite browser it will redirect you to Use the user-agent we used in the previous example to simulate a mobile device. Check out the Firefox extension called “User Agent Switcher” that will let you manually edit your user-agent.

This will let you develop a site dedicated to desktop computers with full multimedia, animations, broadband support, and provide an ad-hoc experience for your mobile visitors. It took less than 10 lines of code, but it will save your life in the next year or so!

Basic layout guidelines

Now consider the number of mobile devices that are being sold every year. Consider that every new device adds a little new feature such as a bigger screen, better connectivity, more colors. We don’t want our visitors to see a black and white page without images if their mobile device supports jpeg images and lots of colors. If we have a tool like WURFL that lets us easily know all about a mobile device it is clear that providing a great user experience becomes a must.

Providing the best user experience is a hard work that requires access to many devices and a LOT of human testing. There is, on the other hand, a shortcut that will allow you to provide a great user experience avoiding much testing. This is what was done on the .mobi official site too.

Prepare 3 different layouts that will cover basic old phones, new colorful phones and the high-level features phones and PDA’s. This is a fairly simple task and at the same time offers great results.

Reaching the best possible user experience means buying at least all the devices that are representative of a larger group and test your site with them. You should probably start with 5-10 very common devices, but if you can get your hands on 20 or more would be even better. Testing should be done on different device brands and browser vendors, some budget phones and some high-end devices. I also suggest that you use emulators. They are not as effective as the real testing, but you will be able to save a lot of time and money. Nokia, Openwave and SonyEricsson all provide free emulators. There are also third party developers such as YoSpace that can provide emulators and development tools.

Tailor your site to all the specific behaviours and supported tags.

Defining device groups

So how can we split mobile devices into three groups? There is not a single rule that applies to all possible sites, it depends a lot on the kind of contents that you want to provide. Depending on the content you will present, the groups may change slightly. Anyhow we can identify three groups that will most likely fit and you will only need to decide the little changes that you want to apply.

The first group, that I will call basic devices, is mostly composed of old devices that hit the market between 1999 and more or less 2002-2003. Often the Ericsson T68 is used to mark the beginning of the next generation of devices. Mobile devices that fall into this first group are devices with a black and white screen or at most a scale of levels of gray (often 4!). These devices generally have a small screen, that will most likely not be more than 110 pixel wide and 80 or 90 pixel high. These devices only support WML 1.0 up to 1.3. wbmp is the image format to use because only a few devices support gif images and having only 2 colors doe not make it really worth using any format aside from wbmp. These devices generally have the minimum memory that was required for WML that is 1392 bytes compiled. I won’t go into the detail of the compiled markup, just remember to keep pages small. This is also a rule that applies to any site for mobile devices and specifically for mobile phones. Scrolling can be a pain, try to keep text at a minimum. Consider splitting content into 2 or more pages.

The second group is made of phones that support colors, from 256 and up to 260K and more. These devices support more complex image formats, from gif to jpeg and png. WBMP is just a legacy format for these devices, supported only to comply with the requirements of WML. Most of these devices support XHTML, so my suggestion is to use this markup whenever you can. There are, unfortunately, some devices such as the Ericsson T68 that supports gif images and can render 256 colors on screen, but has a poor implementation of XHTML. This is because it was the very first device to support it and at the time it was introduced in the market, XHTML-MP was not yet a standard.

The last group is composed by smartphones and PDA’s. Nokia Series 60 such as the 3650, 6600 and the newer models, the SonyEricsson P800, P900 and following all fall into this group. I also put in this group PDA’s such as the BlackBerry, Palm and the other devices running Pocket Windows/PC. These devices all have very big and colorful screens. You might argue that some BlackBerry and Palm used to have grayscale screens and I agree, but you can safely use gif or jpeg images because they have a wide range of grays and are generally rendered very well. Many of these devices also feature a stylus and this makes browsing much easier, clicking a link or scrolling is usually smooth just like on a desktop computer.

You can already see that there might be some mobile phones that don’t fit perfectly in any group, but rather sit on the edge of two groups. The SonyEricsson W800 is an example, it has a very good browser, lots of colors and a fairly big screen. This is one of the adjustments that you should apply depending on the kind of content that you provide and also depending on the install-base of your visitors.

So where is all the information that you need to make these distinctions? WURFL has more than 400 single capabilities that will help you understand which layout you should present, what image formats are supported, which tags are supported or not. Most of the capabilities in WURFL are boolean, this should make it very easy for you to implement your logic. Let’s look at image formats. We have one capability to know about gif, another for jpeg, another one for wbmp. All you have to do is copy and paste this code snippet below:

$supports_gif = $wurflObj-> getDeviceCapability(‘gif’);

‘gif’ is the capability name to know if a device is able to display a gif image in a page.

In the previous example we redirected mobile users from the initial homepage to another host that is made specifically for mobile devices. Now we can build another page that will redirect the browser to the version that we decided to provide. Here is an example of how you can do it.

if ( ereg(‘^wml’, $wurflObj->getDeviceCapability(‘preferred_markup’)) ) {
} else {
if ( $wurflObj->getDeviceCapability(‘resolution_width’) > 160 && $wurflObj->getDeviceCapability(‘colors’) > 256) {
} else {

First of all we check if the preferred_markup of the browser is WML, if not we split into 2 other groups.

preferred_markup is a very particular capability and it is very important. Many modern browsers support more than one mark-up and often more than one version (think of WML 1.0, 1.1, 1.2, XHTML Basic, XHTML-MP, etc). The capability tells you which markup is considered to be displayed best by the current browser. In my simple test I check if the preferred mark-up is WML, if so, I redirect the browser to the “basic” version.

Then I check more capabilities, resolution_width and colors. The former tells me how wide is the screen in pixels, the latter tells me the number of colors the screen is able to display. In my case I considered as enhanced devices all those devices that are at least 161 pixel wide and support more than 256 colors. As I wrote before, these values should be tweaked depending on the content that you are providing and how you want to build your layout. 3 versions are good in most cases, nothing prevents you from building 4 or more versions. If you are really going to build more than 3 versions, you might consider using some software that will actually include the logic to help you an not make you build too many pages manually, but rather generate them dynamically.


Using WURFL does not mean that you can develop a mobile site without testing it with a single device. WURFL just helps you to cover a wide range of devices. I STRONGLY suggest that you buy a few mobile devices, may them be 5-10 or even better 20 and you test the navigation and the layout. This will give you the feel of browsing and will help you to spot little mistakes or pitfalls. It will grant a better experience to your visitors. Once you have tested your site with real devices you will probably be able to tweak the parameters and make the three mobile version fit best to the devices of your users.

Consider buying new devices according to the most common devices of your visitors.

If PHP is not your favorite programming language, but you like what you just read, then you should probably go to the WURFL site anyway and check out the other tools that are available.

If PHP 5 is your language of choice, then you should probably start considering to build your own library. As you will know PHP 5 is slightly different with objects as compared to PHP 4. These libraries are not compatible with PHP 5 and will spit a lot of warning and alerts.

Andrea Trasatti
WURFL co-founder and W3C Invited Expert


Exclusive tips, how-tos, news and comment

Receive monthly updates on the world of mobile dev.

Other Products

Market leading device intelligence for the web, app and MNO ecosystems
DeviceAtlas - Device Intelligence

Real-time identification of fraudulent and misrepresented traffic
DeviceAssure - Device Verification

A free tool for developers, designers and marketers to test website performance
mobiReady - Evaluate your websites’ mobile readiness

© 2023 DeviceAtlas Limited. All rights reserved.

This is a website of DeviceAtlas Limited, a private company limited by shares, incorporated and registered in the Republic of Ireland with registered number 398040 and registered office at 6th Floor, 2 Grand Canal Square, Dublin 2, Ireland