ScientiaMobile Documentation

Start Trial

The WURFL OnSite Database API (Tera-WURFL) has been deprecated and, since February 2017, is no longer supported. Starting from version 1.8 the DB API's features have been merged into the PHP API. The following steps cover how to upgrade from DB API v1.7 or greater.

Note: there are breaking changes in the PHP API release v1.8 and v1.9 (For the full documentation about PHP API please refer to: https://docs.scientiamobile.com/documentation/onsite/onsite-php-api). If you have a different setup or need additional help, feel free to contact us at support@scientiamobile.com.

Requirements

PHP >= 5.4 (suggested 5.6 or higher)
extension: xml (XMLReader)
extension: mysqli or pdo_mysql (for the MySQL adapter)
extension: mongodb (for the MongoDB adapter)
Composer

Updating Dependencies

Extract the v1.8+ PHP API archive as usual and run the following command from the API's root path (i.e. /u/apps/WURFL-API-PHP):

composer install --no-dev --optimize-autoloader

Note: If you are already using Composer in your project, you can add the WURFL API to your composer.json and run composer update to install its dependencies. See the WURFL OnSite PHP API documentation for details.

Bootstrap

Inside your application you must include the new autoloader.

Replace:

require_once "/u/apps/wurfl-db-api-1.x.x.x/TeraWurfl.php";

With:

require_once "/u/apps/WURFL-API-PHP/vendor/autoload.php";

Note: Make sure to replace the paths above with your actual paths!

Configuration

The PHP API uses a dependency container to configure and inject the required dependencies. To configure WURFL you need to create a PHP configuration file returning a Container object.

Create a configuration file (i.e. /path/to/config.php ) – this file will be used to configure the dependencies for the WURFLEngine object and the wurfl-updater tools.

Below is an example configuration with references to values from the deprecated TeraWurflConfig.php file:

use ScientiaMobile\WURFL\Container\Container;
use ScientiaMobile\WURFL\Storage\StorageFactory;
use ScientiaMobile\WURFL\Cache\CacheFactory;

// TeraWurflConfig::$DATADIR. Please note that now it is an absolute path.
$storage_dir = '/u/data/wurfl-api-data';

// TeraWurflConfig::$WURFL_DL_URL
$wurfl_snapshot_url = 'https://data.scientiamobile.com/xxxxx/wurfl.zip';

// See TeraWurflConfig::$PATCH_FILE. Please note that now it is an array of patch files.
// This is normally an empty array, but can be used to load WURFL patch files:
//   $wurfl_patches = ['/full/path/to/patch-1.xml', '/full/path/to/patch-2.xml'];
$wurfl_patches = [];

// TeraWurflConfig::$CAPABILITY_FILTER. Set an empty array to disable the capability filter ($CAPABILITY_FILTER = false)
//   $wurfl_capability_filter = ['device_os', 'device_os_version', ...];
$wurfl_capability_filter = [];

$container = new Container([
    'wurfl_snapshot_url' => $wurfl_snapshot_url,
    'wurfl_storage_path' => $storage_dir,
    'wurfl_patches' => $wurfl_patches,
    'wurfl_capability_filter' => $wurfl_capability_filter
]);

$db_settings = [
    'driver' => 'pdo_mysql', // The extension to use: pdo_mysql or mysqli
    'host' => 'localhost', // TeraWurflConfig::$DB_HOST
    'port' => 3306, // TeraWurflConfig::$DB_PORT
    'db' => 'tera_wurfl_demo' // TeraWurflConfig::$DB_SCHEMA
];

$storage = StorageFactory::createMysqlStorage($db_settings);
$container->setStorageAdapter($storage);

$ttl = 36000;
$cache = CacheFactory::createMysqlCache($ttl, $db_settings);
$container->setCacheAdapter($cache);

return $container;

Note: TeraWurflConfig::$SIMPLE_DESKTOP_ENGINE_ENABLE is specified using the WURFLEngine object, see below.

Loading the WURFL Database with the WURFL Updater Tool

API version 1.8.0.0 introduces WURFL Updater; a new command line utility which is used to automatically update the WURFL database. This is similar to the admin/cmd_line_admin.php script that shipped with the Database API.

To load the local WURFL DB:

php /u/apps/WURFL-API-PHP/wurfl-updater -c /path/to/config.php

Class instantiation

The TeraWurfl class must be replaced with a WURFLEngine object:

Replace:

$wurflObj = new TeraWurfl();

With:

use ScientiaMobile\WURFL\WURFLEngine;

$container = require '/path/to/config.php';

// instantiating the class with a custom dependency container
$wurflObj = new WURFLEngine($container);

Get the Capabilities of the Current Visitor

Replace:

$wurflObj->getDeviceCapabilitiesFromRequest();
// Capability
$is_wireless = $wurflObj->getDeviceCapability('is_wireless_device');
// Virtual capability
$is_smartphone = $wurflObj->getVirtualCapability('is_smartphone');

With:

$device = $wurflObj->getDeviceForHttpRequest();
$is_wireless = $device->getCapability('is_wireless_device');
$is_smartphone = $wurflObj->getVirtualCapability('is_smartphone');

Get the capabilities from an individual User Agent

Replace:

$wurflObj->getDeviceCapabilitiesFromAgent($user_agent);
$is_wireless = $wurflObj->getDeviceCapability('is_wireless_device');

With:

$device = $wurflObj->getDeviceForUserAgent($user_agent);
$is_wireless = $device->getCapability('is_wireless_device');

Configure the Performance Mode Upgrading to PHP API v1.9

IMPORTANT: Decommissioning of Engine Target Options

Prior to version 1.9 of the API, users could choose between High Accuracy and High Performance engine optimization options. These options had been introduced years ago to manage the behavior of certain web browsers and their tendency to present "always different" User-Agent strings that would baffle strategies to cache similar WURFL queries in memory. As the problem has been solved by browser vendors, the need to adopt this strategy has diminished and ultimately disappeared (i.e. there was no longer much to be gained with the high-performance mode in most circumstances) and ScientiaMobile elected to "remove" this option to simplify configuration and go in the direction of uniform API behavior in different contexts.

To clarify "remove" in the previous sentence, customers who may find themselves in the unlikely situation of having to analyze significant amounts of legacy web traffic, may still enable the old high-performance internal behavior by enabling the "FAST DESKTOP BROWSER MATCH" option on their engine. Please note that users with the old HIGH PERFORMANCE target engine will not receive an error. The old behavior will not be triggered, though. The default target (corresponding to the old High Accuracy) will be used instead. The WURFL Engine is the API's entry point. The WURFL Engine can be created using a factory method or simply instantiating the class.

For more details please refer to: https://docs.scientiamobile.com/documentation/onsite/onsite-php-api If you need additional help feel free to contact us at support@scientiamobile.com.