WURFL

Home / PHP

WURFL and PHP
Configuration file

Downloads
PHP Tools version 2.1 Final

Andrea Trasatti
PHP Tools version 2.1 Final

WURFL and PHP: The configuration file
by Andrea Trasatti (atrasatti at users dot sourceforge dot net)

Introduction

The first thing you should do after you have downloaded the PHP library and the wurfl.xml is to configure the library so that it will work properly.
The PHP library offers many configuration parameters, maybe too many. The scope of this page is to try to give a few guidelines about how to configure your scripts properly. For the basic description of each single configuration parameter please check the main page, labeled "WURFL and PHP" in the left menu.

The basic parameters

The library will not be able to work properly and give you an error on screen if you do not configure the very basic parameters. The library is composed first of all of three files, the configuration, the parser and the class. The library will not be able to work if you don't have the wurfl.xml, of course!
These parameters are the very first to be configured.
Open wurfl_config.php with your favorite editor ('vim' is mine), read the comments to get more help about each single configuration parameter and then proceed to configure the basic parameters.
Skip WURFL_CONFIG, just leave it set to true. This simply tells to the parser and to the class that we have included the configuration file. More on this later.
DATADIR, by default it's configured with '../data/'. In general the PHP libraries will put support files in DATADIR. You might want to put the parser and the class there too. It's just a matter of how you want to organize your software. There are no real constraints. Just make sure the webserver will have the rights to write in this directory, because cache files will be stored here.
WURFL_PARSER_FILE, this directive is mandatory. The default is to pick the parser from the local directory. Change this if you have placed the file somewhere else. My suggestion is to leave the class and the parser together, but this is just a matter of tastes. I would not leave these libraries in the same directory as the scripts that will be accessed from the web/wap. Remember to refer to the path and filename. The path can be relative. And absolute path should work better if you ever decide to move the files around, a relative path will be more comfortable if you make a package and install it on different servers with different base path.
WURFL_CLASS_FILE, this directive is mandatory. Same as above, put it where you like it best as fix this define.
WURFL_FILE, this directive is mandatory. Same as above, put it where you like it best as fix this define. By default this is placed in DATADIR.
WURFL_LOG_FILE, this directive is mandatory. Same as above, put it where you like it best as fix this define. By default this is placed in DATADIR.
LOG_LEVEL is important to know what's going on. I don't think anyone will be happy to have problems and not know what is happening. While the logging features are not many in these libraries because we only want to make sure that the scripts are working, they still might be useful to know if anything bad has happened. One of the most common problems is a wrong cache file (generated with wrong settings) and then the class doesn't find the devices. Don't underestimate the logs.

Cache

Caching is very important in our case. The XML is pretty big and will only keep growing in the future. XML parsing is not so fast and we also have to follow the fall_back tree to get all the capabilities of a device. All this takes time and only reading the XML from the filesystem at each hit of the web server takes time. To avoid this we have 2 main caching systems (that you can choose) and a "device caching" that is the same for both.
Let's first talk about how they work and then we can see how to configure them.
Knowing the two systems will help you to choose the most appropriate and configure it properly.

Classic Cache
The original solution was very simple, after reading the entire XML and transform it into an associative array, it was stored in a big file. At every second hit, the PHP would read the file with the associative array and have it ready in memory instead of parsing the XML and generate the same array.
This was a good solution at the beginning, then the file started to grow. Now the file is bigger than 2 megabytes and a PHP cache is STRONGLY suggested. If you will choose to use this system, I suggest you to use Zend Accelerator or Turck cache or APC Cache 2.0 or eAccelerator.
Which are the advantages of this caching system?

1 single cache file
easy to cleanup and regenerate
easily cached in shared memory

MultiCache
With the growing size of the cache file, some users started having some problems loading the cache file after it was generated. A much more performing system was to create many tiny files, one for every device in WURFL. They would have been much faster to be loaded. This is exactly the opposite of the "Classic Cache", many little files that get loaded at every hit instead of a big single file.
When the multicache is generated, the system creates as many files are the devices in WURFL. Each files contains any capability that is defined in the XML. When a device hits your site, the class searches for it in the list of user agents, finds the appropriate wurfl_id, and loads the file from the multicache, reads the fall_back (which is another wurfl_id) and loads it until the "generic" is reached. This means that the library will load an average of 3-4 files per hit. Which are the advantages of this caching system?

not a single cache file, but many little files
no need of a PHP cache

Things in common
Both caching systems will generate a file called "cache.php" by default (you can change this using the "CACHE_FILE" directive). $wurfl_agents will be stored in this file. $wurfl_agents is an associative array that tells the system the wurfl_id of every known user agent. This speeds the search.
$cache_stat will tell the system when the cache file was generated. This is needed if you want the cache to be updated automatically.
Another small cache file will be created, the default name is agent2id.php4, you can change it with WURFL_AGENT2ID_FILE. The file stores the last devices that hit your site avoiding to search for them at each hit. The limit of devices stored is configured using MAX_UA_CACHE, 30 is a good number for a small site, while 50 should be a good number for a large site. Change this at your wish.

Cache comparison
There isn't a caching system better than the other, both have their pros and cons. You should choose the "Classic Cache" if you want a simple and clean cache. A PHP Cache is needed, but having the associative arrays in memory could give you some performance advantages. The automatic update of cache.php is easier and you shouldn't have any race condition, or at worse, two processes will generate the same file and overwrite each other.
The MultiCache system solves some of the problems of the other system, but might not be the perfect solution for everyone. The big advantage is the generation of many tiny files avoiding memory problems when loading the file from the harddisk, this should be a great improvement for everyone with limited resources. On the other side someone with I/O problems might find this solution not very comfortable. Also consider that updating the cache is very uncomfortable because many files will be generated and many others removed, for this reason the "update_cache.php" script was developed. This script should help anyone wanting to use the "MultiCache". Another reason to use the "MultiCache" is that in many cases it proved to be faster.
If you are installing a new server, my suggestion is to try the "MultiCache", if you have used the "Classic Cache" without problems, just keep using it, there is not plan to stop supporting any of the systems in the near future.

How to configure the cache
You will necessarily need to configure WURFL_USE_CACHE to true if you want to use any of the systems.
You will also to make sure that the webserver is allowed to read and write the file speficied in CACHE_FILE, here $wurfl_agents and $cache_stat will be stored in any case. WURFL_AGENT2ID_FILE will store the temporary cache of the last user agents that visited your site.
If you want to use the Classic Cache you're done, if you want to try the other cache system you will need to configure more parameters. First of all you will have to set WURFL_USE_MULTICACHE to true. You will also want to define the path were the files will be generated, use MULTICACHE_DIR and MULTICACHE_SUFFIX to define the extension of the generated files. When the library will update the cache files (wether using update_cache.php or automatically) these parameters will be used, MULTICACHE_TMP_DIR and MULTICACHE_TOUCH, the former tells the library where to temporarily store the new files created and the latter will be used as a lock file. To avoid race conditions, a locking system was implemented, the new files are generated in a temporary directory and then moved. The old directory will be renamed with a timestamp so the webserver will need to have the rights to do this (or the user that runs update_cache.php).

Autoloading and autoupdating
The PHP libraries also allow you to define if you want to load (and parse) automatically the XML file at each run. This is configured using WURFL_AUTOLOAD, this is useful only if you are not using any cache system. By default this is set to false. If you don't want to use the cache set it to true.
If you are using any of the cache systems you might want the cache files to be updated automatically when a new XML is installed. If you want so set the WURFL_CACHE_AUTOUPDATE to true. It is worth to set this to true if you don't want to bother updating the cache and if you are using the Classic Cache. Some race conditions might happen with the MultiCache so this combination is not suggested. For a production environment can be worth setting this to false and use the "update_cache.php" script to manually update the cache files when needed. The drawback is that you will have to do it manually.
NOTICE: If you plan to update your cache manually you will HAVE to generate the cache files manually even the very first time. This is a new feature introduced in the PHP Library V2.1 Beta 2, previously it was automatic.

update_cache.php
This script will force a cache files update. Wether the XML is new or old, all the cache files will be cleared and regenerated.