Tera WURFL: Get mobile device capabilities from WURFL+MySQL

Tera-WURFL README
Version Stable 1.5.2
http://www.tera-wurfl.com/
-----------------------

New in 1.5.2 ---> the $wurflObj->getDeviceCapabilitiesFromAgent() function
now returns boolean true or false.  This tells you whether there was a match
(true) or not (false).  In previous versions you had to check if the
capabilities array contained usable data.
ALSO, two new config options are available:
 * MATCH_TO_UA_PREFIX	boolean, if true, matching will stop if the user
                        agent prefix cannot be matched.  The user agent prefix
                        is everything from the beginning of the UA to the
                        first '/', like "SonyEricssonK700i".  If this is not
                        matched in the WURFL, there searching will stop.
 * RETURN_GENERIC		boolean, if true, the user agent and accept headers
                        will be used to determine if this device is wireless
                        or not and the capabilities array will be populated
                        with approporiate generic data.  This IS considered
                        a match.  Set this to false to stop getting generic
                        matches.

Tera-WURFL 1.5.2+ includes an XML webservice file called webservice.php
it is currently a BETA feature, but it should to be pretty fail-safe.
Information on this features usage is included in the webservice.php file.

Tera-WURFL 1.5.x includes a high speed caching system.  This
means that if you are upgrading, you will see that another table will be
created to store the cached results of your past queries.  This system
has been tested on some very high traffic sites and is said to have increased
performance dramatically!

"The system gets over 2 million WAP hits per day ... The impact on the server 
is definitely significant. Before this, mysqld was using between 20% and 40%
of the CPU, and now it's down to 6% or less. Load average on the box was
averaging 3.84 before, and now it's averaging 2.72."

JUST GET ME TO THE INSTALLATION!
Ok, it took me a lot longer to write this then it will take you to read it,
so please read EVERYTHING from INSTALLATION on.  Feel free to email me if
you need help with anything, or to request new features!

ABOUT TERA-WURFL
Tera-WURFL is a PHP & MySQL based library that uses the Wireless Universal
Resource File (WURFL). The WURFL website  nicely defines the WURFL as
follows: "The WURFL is an "ambitious" configuration file that contains
info about all known Wireless devices on earth. Of course, new devices are
created and released at all times. While this configuration file is bound 
to be out of date one day after each update, chances are that the WURFL 
lists all of the WAP devices you can purchase in the nearest shops."

Tera-WURFL is loosely based on the original PHP Tools Library by Andrea 
Trasatti and serves as a drop in replacement with only minor changes to 
your existing code. Since Tera-WURFL uses a MySQL database backend, the 
real world performace increase over the existing PHP Tools (with multicache) 
implementation is extremely high - normally between 5x and 10x faster!
The author of Tera-WURFL is Steve Kamerman, a professional PHP Programmer,
MySQL DBA, Flash/Actionscript/Javascript Developer and Linux Administrator.
This project is financially sponsored by Tera Technologies and was originally
an internal project used for delivering content to customers of the mobile
ringtone and image creation site www.Tera-Tones.com.

Read more about Tera-WURFL and download the latest release at:
http://www.tera-wurfl.com/

See what else Steve Kamerman has cookin' at his blog:
http://www.teratechnologies.net/stevekamerman/

INSTALLATION
1. Copy the files into a directory on your webserver that can be accessed
   from the internet.  For the purposes of explaination I will refer to this
   location as "http://yourserver.com/tera_wurfl/", with a local directory
   of "/var/www/tera_wurfl/".
2. Open a web browser and go to:
   "http://yourserver.com/tera_wurfl/admin/install.php"
   you should see the "Tera-WURFL Installation" page with a bunch of errors
   on it.  The next steps will show you how to correct these errors.  You 
   can refresh this page to verify that your changes have taken effect.

CONFIGURATION FILE
3. Edit the tera_wurfl_config.php file.
   a. Make sure WURFL_PATCH_ENABLE is set to true if you want to use the
      included web_browsers.xml patch file.  You will need this patch to
      determine whether the visitor is using a wireless device or a
      desktop web browser.
   b. Make sure the DB_EMPTY METHOD is set to "DROP_CREATE" - this will
      automatically create the database tables for you.
   c. The rest of this guide will refer to this file for configuration
      instructions.

FILE PERMISSIONS
4. If you downloaded the "Lite" version of Tera-WURFL, the wurfl.xml file
   is not included in the package.  You will see a warning in the install
   script telling you that it cannot be accessed.  This is ok, since you
   will still be able to update it from the WURFL website.
5. 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. (chown -R apache:apache ./data/)
6. Verify that the permissions errors on the installation page are fixed
   by refreshing the browser.
   
DATABASE OPTIONS
7. Create a new database for Tera-WURFL and a user that has a minimum of
   the following privileges on the new database:
      SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER
8. In the config file, set the DB_HOST, DB_USER, DB_PASS and DB_SCHEMA.
9. 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.

LOADING THE Tera-WURFL DATABASE
10.If you are satisfied with the results on the installation page, you
   can load the database with the WURFL data.  There are three sources
   that the data can come from:
   a. Your local WURFL file
      This will load the DATADIR/wurfl.xml file into your database.
   b. The current released WURFL
      This will download the current wurfl.xml file from the official
      WURFL website (to DATADIR/dl_wurfl.xml) and load it into your
      database.
   c. The current CVS WURFL
      This will download the current unreleased CVS wurfl.xml file from
      the official WURFL website (to DATADIR/dl_wurfl.xml) and load it
      into your database.
11.There will be a delay while the server loads/downloads the WURFL, then
   you should see something like this:

Downloading WURFL from http://wurfl.cvs.sourceforge.net/%2Acheckout%2A/wurfl/xml/wurfl.xml ... 
done (4830831 bytes)
Database Update
--------------------------------------------------------------------------------
WURFL Version: Wireless Universal Resource File v_2.0.8 (June 5, 2007)
Total Update Time: 13.725301980972
Total Devices in WURFL: 6626
Total Devices inserted in DB: 6626
Total Queries: 14
Largest Query: 344KB
Total Errors: 0

Applying Patch
--------------------------------------------------------------------------------
Total Update Time: 0.26863980293274
Total Devices in Patch File: 0
New Devices Added: 0
Merged Devices: 0
Total Queries: 5
Total Errors: 0

Update Complete!
   
   If there are errors, they are most likely problems connecting to the WURFL
   site or permission problems trying to write the downloaded file (dl_wurfl.xml)
   to the DATADIR directory.  Also, some users have reported a "memory allocation"
   error - to fix this look for "Set Max Memory Limit" in the config file. If 
   there are no errors, click on "Return to administration tool".

ADMINISTRATION PAGE
12.Verify that the WURFL is loaded by clicking on "Statistics, Settings,
   Log File".  You should see that there is data in your DE_DEVICE_TABLE
   and your DB_HYBRID table.  If you loaded the patch file, you will also
   see data in your DB_PATCH_TABLE.  The DB_CACHE_TABLE will fill up with
   cached data as devices access your site, and it will be cleared anytime
   you update EITHER your patch database or your main WURFL database.
13.Click on "Tera-WURFL test script" to test the installation.  You can
   type in any user agent to search for it in the WURFL.  If you have caching
   enabled (default), the first time you search for a user agent you will see
   the total number of queries that Tera-WURFL performed to find a match
   (unless there was no match).  If there was a match, the device will be
   cached and the next time you search for it you will see "Total Queries: 1
   (Found in cache)".  Tera-WURFL only needed to perform 1 query since the
   devices full capabilities were cached.  If you go back to the admin page
   and look at the settings, you will see that the DB_CACHE_TABLE now has
   a couple rows in it.  Sweet success!
   
SECURITY
14.You should delete the admin/install.php file if everything is working ok.
15. Protect your 'admin' directory by using a method specific to your web
   server software.  For Apache, this means a .htaccess file would work:
   http://www.mobilefish.com/developer/apache/apache_quickguide_htaccess.html#protect

EXAMPLE
Here is a very simple example:
<?php
// Include the Tera-WURFL file
require_once('./tera_wurfl.php');

// instantiate the Tera-WURFL object
$wurflObj = new tera_wurfl();

// Get the capabilities of the current client. $matched will be true if Tera-WURFL
// found a match for the device and false if not.
$matched = $wurflObj->getDeviceCapabilitiesFromAgent($_SERVER['HTTP_USER_AGENT']);

// see if this client is on a wireless device (or if they can't be identified)
if(!$matched || !$wurflObj->getDeviceCapability("is_wireless_device")){
	echo "<h2>You should not be here</h2>";
}

// check if there is a picture of this device
if($wurflObj->device_image != ''){
	// display device image
	echo '<img src="'.$wurflObj->device_image.'" /><br />';
}

// see what this device's preferred markup language is
echo "Markup: ".$wurflObj->getDeviceCapability("preferred_markup");

// see the display resolution
$width = $wurflObj->getDeviceCapability("resolution_width");
$height = $wurflObj->getDeviceCapability("resolution_height");
echo "<br/>Resolution: $width x $height<br/>";
?>

The complete list of capabilities is available here:
http://wurfl.sourceforge.net/help_doc.php#product_info
If you use $wurflObj->getDeviceCapability("cap_name") you can just use the capability name from
the WURFL site, otherwise you can access it directly from the wurfl object's
capabilities array like this: $wurflObj->capabilities['group_name']['cap_name']

Please see the test script (check_wurfl.php) for another example of usage.
There are also a couple more examples of how to use Tera-WURFL in the main
class file - tera_wurfl.php.

SUPPORT

You may contact me, Steve Kamerman with questions - once I feel that there
are too many emails to deal with I will probably put up a forum, but since
this project is still fairly new, I will just help you all out over email.

Here's my email address: kamermans(at)teratechnologies.net
      
NOTE: The public methods from the WURFL PHP Tools class at 
wurfl.sourceforge.net are avalible in this class and they all use the same
syntax as before with the exception of the constructor - "tera_wurfl" which has
been renamed from "wurfl_class".