onsite php database api

WURFL OnSite PHP Database API: User Guide

Please note - With the introduction of PHP API v1.8.0.0, PHP Database API (TeraWURFL) is now legacy and will be fully supported until February 2017.

Requirements

  • PHP 5.3+
  • Web Server (the following have been tested):
    • Apache
    • lighttpd
    • NGINX with FastCGI
    • IIS
    • HipHop (HHVM) 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

To enable WURFL on your application you must register for a free account on scientiamobile.com and download the latest release from your File Manager. Once you have downloaded the latest release, you will need to extract the files to be accessible from your PHP enabled webserver.

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 MySQL5.x. If you are using a different database, set the DatabaseConnector accordingly (see Requirements above).

Note: The WURFL API is closely tied to the wurfl.xml file. New versions of the wurfl.xml are compatible with old versions of the API by nature, but the reverse is not true. Old versions of the wurfl.xml are not guaranteed to be compatible with new versions of the API.

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 by editing the $CAPABILITY_FILTER option in TeraWurflConfig.php.

public static $CAPABILITY_FILTER = array(
    "device_os",
    "device_os_version",
    "is_tablet",
    "is_wireless_device",
    "pointing_method",
    "preferred_markup",
    "resolution_height",
    "resolution_width",
    "ux_full_desktop",
    "xhtml_support_level",
    "is_smarttv",
    "can_assign_phone_number",
    "brand_name",
    "model_name",
    "marketing_name",
    "mobile_browser_version",
);

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.

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 configuration 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. You can verify that all credentials are functional by visiting admin/install.php If the database tables do not exist yet they will be created for you when you load the WURFL file in the next step.

Your installation page should look similar to:

Database API 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 two sources that the data can come from:

  • Your local WURFL file: This will load the DATADIR/wurfl.xml file into your database.
  • 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 configuration file with your Direct Download URL.

There will be a delay while the server loads/downloads the WURFL, then you should see a page similar to:

Database Update OK
Total Time: 45.738869905472
Parse Time: 7.7668120861053 (TeraWurflXMLParser_XMLReader)
Validate Time: 15.274527072906
Sort Time: 15.177093982697
Patch Time: 7.8678131103516E-6
Database Time: 7.5046010017395
Cache Rebuild Time: 0.015827894210815
Number of Queries: 506
PHP Memory Usage: 65.37 MB
--------------------------------
WURFL Version: db.scientiamobile.com - 2015-01-01 00:00:00 (Thu Jan 01 00:00:00 -0400 2015)
WURFL Devices: 34724
PATCH New Devices: 3036
PATCH Merged Devices: 2

If there are any 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, which can be corrected by increasing OVERRIDE_MEMORY_LIMIT in the config file.

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:

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

Virtual Capabilities

Virtual capabilities are an important feature of the WURFL API that obtain values related to the requesting agent out of the HTTP request 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 profiles in WURFL.

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

$is_smartphone = $wurflObj->getVirtualCapability('is_smartphone');

Variable Name Type Description
is_app enumerable Tells you if the Requesting HTTP Client is an App or not. The control capability is called is_app (virtual_capability group) and can have values default, force_true and force_false
is_smartphone enumerable This is a virtual capability that will tell you if a device is a Smartphone for some arbitrary (and subject to change) definition of Smartphone by ScientiaMobile.

The virtual capability returns true or false. Patch files can use the is_smartphone control capability to override the value returned by the virtual capability.

Control capability is_smartphone can take value default, force_true and force_false.

is_robot enumerable This is a virtual capability that tells you if the HTTP Client is a Bot (robot, crawler or other programmable agent that stalks the web).
Control capability is is_robot (virtual_capability group) and can have values default, force_true and force_false.
is_mobile enumerable This is just an ALIAS for is_wireless_device. There's no control capability associated to this virtual capability.
is_full_desktop enumerable This is just an ALIAS for ux_full_desktop. There's no control capability associated to this virtual capability.
is_windows_phone enumerable Check if device runs any version of Windows Phone OS.

This virtual capability relies on the device_os (product_info group) capability.

is_ios enumerable Check if device runs any version of iOS.

This virtual capability relies on the device_os (product_info group) capability.

is_android enumerable Check if device runs any version of Android OS.

This virtual capability relies on the device_os (product_info group) capability.

is_touchscreen enumerable This virtual capability tells you whether a device has a touch screen. There is no control capability. Mostly an alias for pointing_method == touchscreen (product_info group) capability.
is_largescreen enumerable True if the device has a horizontal screen resolution greater than 320 pixels. Relies on the resolution_width (display group) capability.
is_wml_preferred enumerable True if the device is better served with WML. Capability relies on preferred_markup (markup group).
is_xhtmlmp_preferred enumerable True if the device is better served with XHTML MP (Mobile Profile). Capability relies on preferred_markup (markup group).
is_html_preferred enumerable True if the device is better served with HTML. Capability relies on preferred_markup (markup group).
advertised_device_os string This virtual capability will infer the name of the Device OS based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).
advertised_device_os_version string This virtual capability will infer the name of the Device OS Version based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).
advertised_browser string This virtual capability will infer the name of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).
advertised_browser_version string This virtual capability will infer the name of the browser based on user-agent string analysis (and possibly the analysis of other HTTP headers and WURFL capabilities).
form_factor enumerable This virtual capability will return one of the following values that identify a client's form factor: Desktop, Tablet, Smartphone, Feature Phone, Smart-TV, Robot, Other non-Mobile, Other Mobile
complete_device_name string Concatenates brand name, model name and marketing name (where available) of a device into a single string.
is_phone enumerable This is a virtual capability that will tell you if a device is a mobile phone .

The virtual capability returns true or false. Patch files can use the is_phone control capability to override the value returned by the virtual capability.

Control capability is_phone can take value default, force_true and force_false.

is_app_webview enumerable This virtual capability returns true if a HTTP request is from an app based webview.
device_name string Concatenates brand name and marketing name of a device into a single string. If marketing name is not available, model name is used instead.
advertised_app_name string This virtual capability will return the name of the application that generated the User-Agent or the HTTP request.

License

2017 ScientiaMobile Incorporated All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from ScientiaMobile Incorporated.