onsite php api

WURFL OnSite PHP API: User Guide

Please note - there are breaking changes in API release v1.8. For documentation of releases before API v1.8 please refer to the README file included with that version. If you need aditional help for versions prior to 1.8 feel free to contact us at support@scientiamobile.com

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.

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.

Requirements

  • PHP >= 5.4 (suggested 5.6 or higher)
  • extension: xml (XMLReader)
  • Composer

Install dependencies

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

Adds WURFL PHP API to an existing project using composer.json

If your project uses Composer, you can simplify maintenance by specifying the WURFL PHP API as an artifact repository:

  • copy the WURFL PHP API ZIP package in a folder which will contain the archives
  • add the following configuration to your composer.json:

    "repositories": [
          {
              "type": "artifact",
              "url": "/path/to/directory/with/zips/"
          }
      ],
      "require": {
          "scientiamobile/wurfl-api": "*"
      }
    
  • run composer install to install the dependencies

Note: To update the package, simply copy the new ZIP archive in the package folder and run composer update

Configuring WURFL

Starting in version 1.8.0.0, the 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.

As reference or starting point, please refer to the config/config.php.example file.

  1. Create a new WURFL Dependency Container with optional settings

    // Example: Create WURFL Dependency Container
    $container = new \ScientiaMobile\WURFL\Container\Container([
      'wurfl_snapshot_url' => 'https://data.scientiamobile.com/xxxxx/wurfl.zip',
      'wurfl_capability_filter' => [
          'device_os',
          'device_os_version',
          ...
      ],
      'wurfl_patches' => [
          '/full/path/to/patch-1.xml',
          '/full/path/to/patch-2.xml',
          ...
      ],
      ...
    ]);
    

    The Container takes an optional argurment as an associative array of settings with the following keys:

    • wurfl_db: a full path to the WURFL DB file (default to: resources/wurfl.xml)
    • wurfl_snapshot_url: The WURFL Snapshot URL from your customer vault on scientiamobile.com. Ex. https://data.scientiamobile.com/xxxxx/wurfl.zip.
    • wurfl_patches: an array containing the WURFL patches' full path
    • wurfl_capability_filter: an array with the capabilities to load in order to reduce memory usage and increase performance
    • wurfl_storage_path: the absolute path to the storage dir. Default to "storage"
    • wurfl_debug: a boolean that enables the debug mode (default to: false)

    Note: if wurfl_snapshot_url is specified the wurfl_db setting will be ignored.

  2. Create a Storage adapter using either the StorageFactory, or by simply instantiating one of the Storage classes.

    The API supports the following storage mechanisms:

    • File (default)
    • SQLite through the PDO extension
    • Redis through the redis extension
    • MySQL through the PDO or the mysqli extension
    • MongoDB through the mongodb extension
    • Memory
    // Example: Create a File storage adapter
    use ScientiaMobile\WURFL\Storage\StorageFactory;
    $storage = StorageFactory::createFileStorage('/path/to/storage/folder');
    
  3. Create a Cache adapter using either the CacheFactory factory, or by simply instantiating one of the Cache classes.

    The API supports the following caching mechanisms:

    • File (default)
    • APCu (APC User Cache)
    • Redis
    • SQLite
    • Memcache
    • MySQL
    • Null (no caching)
    // Example: Create a File cache adapter
    use ScientiaMobile\WURFL\Cache\CacheFactory;
    use ScientiaMobile\WURFL\Cache\CacheAdapterInterface;
    
    // Time to live for cache item
    $ttl = CacheAdapterInterface::NEVER; //Default
    $cache = CacheFactory::createFileCache($ttl, '/path/to/storage/folder');
    
  4. Add the storage and cache adapters to the container

    $container->setStorageAdapter($storage);
    $container->setCacheAdapter($cache);
    

Note: Since the default configuration uses the File adapter for both Storage and Caching, you'll need to make sure your webserver can write to the storage directories.

Note: As reference on how configure and use the Evalution version please refer to the section: WURFL PHP API Basic Usage for the Evaluation version

WURFL Updater

API version 1.8.0.0 introduces WURFL updater; a new command line utility which allows a client using WURFL to automatically update while the standard WURFLEngine is running and serving requests. In order to use the WURFL Updater, you must have your personal WURFL Snapshot URL (wurfl_snapshot_url) in the following format: https://data.scientiamobile.com/xxxxx/wurfl.zip where xxxxx is replaced with you personal access token. Also, do note that the wurfl_storage_path specified in the dependency container must be writable from the process/task.

The wurfl-updater utility is located under:

  • /your/project/root/path/vendor/bin/ for project that uses the API as composer dependency
  • /path/to/wurfl-api/ for project that uses the API as standalone library

The wurfl-updater utility can be used to run on demand or periodic updates.

Running “periodic” updates.

This is the suggested configuration since allows to periodically check if a new version of the wurfl.zip has been released, and if so, download it and build the repository with the new version.

The simpliest way to enable periodic updates is to use a time-based job scheduler like crontab:

# Crontab example
# .--------------- minute (0 - 59)
# | .------------- hour (0 - 23)
# | |   .--------- day of month (1 - 31)
# | |   | .------- month (1 - 12) OR jan,feb,mar,apr ...
# | |   | | .----- day of week (0 - 6) (Sunday=0 or 7)  OR sun,mon,tue,wed,thu,fri,sat
# | |   | | |
# * *   * * *   <user>  <command>

# Run wurfl-updater script with daily frequence
30 3 * * *       www-data  /path/to/php -d memory_limit=1024M /path/to/wurfl-updater -c /path/to/config.php > /dev/null

Running “on demand” update.

php -d memory_limit=1024M /path/to/wurfl-updater -c /path/to/config.php

On demand update runs only once per call.

WURFL PHP API Basic Usage

require_once './vendor/autoload.php';

// Require the dependency container object
$container = require_once '/path/to/config/config.php';
// Create a new instance of WURFLEngine
$wurfl_engine = new \ScientiaMobile\WURFL\WURFLEngine($container);
// Get the device for the current request
$device = $wurfl_engine->getDeviceForHttpRequest();
// Get the value for a capability
$device->getCapability("is_wireless_device");
// Get the value for a virtual capability
$device->getVirtualCapability("is_smartphone");

WURFL PHP API Basic Usage for the Evaluation version

The Evaluation package comes with an XML file containing several of our popular WURFL Device Capabilities that can be loaded directly from the API without the use of the WURFL Updater.

require_once './vendor/autoload.php';

// Require the dependency container object
$container = new \ScientiaMobile\WURFL\Container();
// Build the WURFL Repository using the WURFL evaluation XML
\ScientiaMobile\WURFL\Repositories\RepositoryManager::build($container);
// Create a new instance of WURFLEngine
$wurfl_engine = new \ScientiaMobile\WURFL\WURFLEngine($container);
// Get the device for the current request
$device = $wurfl_engine->getDeviceForHttpRequest();
// Get the value for a capability
$device->getCapability("is_wireless_device");
// Get the value for a virtual capability
$device->getVirtualCapability("is_smartphone");

Note: Since with this configuration the WURFL repository is built directly from the WURFL API, the first request could takes some seconds to be served

Capability Filtering

In order to reduce memory usage and increase performance, specify a subset of the 500+ WURFL capabilities. You can set the desired capabilities as settings in the Dependency Container:

// Example: Create WURFL Dependency Container
$container = new \ScientiaMobile\WURFL\Container\Container([
    'wurfl_capability_filter => [
        'device_os',
        'device_os_version',
        ...
    ]
]);

If you make any changes or add a capability filter, you will need to reload the WURFL file and only the capabilities you've specified will be loaded. Note that the auto-reload system will not detect the change in your configuration and reload the WURFL data automatically, so you will need to either touch the WURFL file or delete your persistence folder.

Note: If you are upgrading from a previous version, remember that starting in WURFL API version 1.8.0.0, you don't need to specify WURFL mandatory capabilities anymore.

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 parameters 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 retrieve the value of a virtual capability, use the getVirtualCapability() method from a Device object:

$is_smartphone = $device->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.

Examples

There is a usage example included with the PHP API in the examples/demo folder.

The file examples/demo/index.php demonstrates how you can use the API to display the capabilities of a visiting device.

License

2016 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.