Moving to WURFL OnSite PHP API from WURFL OnSite Database API (formerly Tera-WURFL)

 

 

Starting from version 1.8 the DB API’s features have been merged in the PHP API.

WURFL OnSite Database API (Tera-WURFL) will be supported until February 2017.

This upgrade guide will show how to upgrade from DB API >= 1.7.

For the full documentation about PHP API please refer to: https://docs.scientiamobile.com/documentation/onsite/onsite-php-api

Note: there are breaking changes in the PHP API release v1.8. 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/vendor/bin/wurfl-updater -c /path/to/config.php

Class instantiation

The TeraWurfl class must be replaced 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);

Configure the performance mode

By default, the WURFL Engine runs in high accuracy mode. To override the default and enable performance mode (i.e. $SIMPLE_DESKTOP_ENGINE_ENABLE = true):

$wurflObj->enablePerformanceMode();

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