Zend_Http_UserAgent

Overview

With the plethora of mobile devices available on the market, it's increasingly important to be able to identify the capabilities of those devices in order to present content in a an appropriate way. For instance, if the device is not capable of displaying images, you might want to omit them from the markup; alternately, if a device is capable of Flash, you may want to provide a Flash-based user interface.

The process of identifying a device's capabilities typically first requires knowing the HTTP User Agent, and then comparing that user agent against a database of user agent capabilities. Zend_Http_UserAgent was created to provide these capabilities for your applications. It consists of several major features:

The primary Zend_Http_UserAgent class, which detects the User Agent, and gives you a device object, as well as persists the device object for later retrieval.
A Zend_Http_UserAgent_Device interface, and a number of implementations that implement it. These objects utilize a features adatper to discover device capabilities, and then allow you to introspect those capabilities.
A Zend_Http_UserAgent_Features_Adapter interface; concrete implementations provide the ability to discover device capabilities, or features.
A Zend_Http_UserAgent_Storage interface, which is used to persist discovered devices for given users, allowing for faster device capability discovery on subsequent page visits.
A view helper that can be used within your view scripts and layouts to branch display logic based on device capabilities.
A Zend_Application resource for configuring and instantiating the user agent object, as well as seeding the view helper with the user agent object instance.

At the time of this writing, The UserAgent component provides three adapters:

Zend_Http_UserAgent_Features_Adapter_Browscap utilizes PHP's native get_browser() in conjunction with browscap. While the database featureset is not as fine-grained as other projects, for the majority of purposes, it provides reliable, fast results.
Zend_Http_UserAgent_Features_Adapter_TeraWurfl consumes the TeraWurfl API, which is built on top of WURFL, and aimed at providing a highly available, highly performant lookup mechanism.
Zend_Http_UserAgent_Features_Adapter_DeviceAtlas consumes the DeviceAtlas API, which is a paid, Enterprise-grade mobile device capabilities database.

Quick Start

First, you will need to download the php_browscap.ini if you do not already have it installed on your system:

php_browscap.ini

We suggest that you put the file in the same directory as your php.ini.

Next, notify PHP of the browscap file via the browscap setting. Because this setting is of type PHP_INI_SYSTEM, this must be done either in your php.ini or web server configuration; it cannot be done in htaccess or via ini_set(). We recommend adding it to your php.ini.

browscap = /path/to/php_browscap.ini

If you put php_browscap.ini in the same directory as your php.ini, this can be reduced to simply:

browscap = php_browscap.ini

Now, edit your application.ini to add the following lines to your [production] section:

resources.useragent.mobile.features.classname = "Zend_Http_UserAgent_Device_Features_Browscap"

At this point, everything is setup. Each request will contain detailed information on the user agent.

You can access this information in a variety of ways. From within the MVC portion of your application, you can access it via the bootstrap. Within plugins, this is done by grabbing the bootstrap from the front controller.

$bootstrap = Zend_Controller_Front::getInstance()->getParam('bootstrap');
$userAgent = $bootstrap->getResource('useragent');

From your action controller, use getInvokeArg() to grab the bootstrap, and from there, the user agent object.

$bootstrap = $this->getInvokeArg('bootstrap');
$userAgent = $bootstrap->getResource('useragent');

Within your view, you can grab it using the UserAgent view helper.

$userAgent = $this->userAgent();

Once you have the user agent object, you can query it for different capabilities. As one example, you may want to use an alternate layout script based on the user agent capabilities.

$device = $userAgent->getDevice();

$cssSupport    = $device->getFeature('cssversion');
$jsSupport     = $device->getFeature('javascript');

switch (true) {
    case ($jsSupport && $cssSupport >= 3):
        $layout->setLayout('layout-html5');
        break;
    case ($jsSupport && $cssSupport < 3):
        $layout->setLayout('layout-xhtml');
        break;
    case (!$jsSupport && $cssSupport < 3):
        $layout->setLayout('layout-html-transitional');
        break;
    default:
        $layout->setLayout('layout-web-1');
        break;
}

Finally, each device will often have a large number of capabilities not immediately represented in the device interface. You can query these using the hasFeature() and getFeature() methods, or simply grab all of them with getAllFeatures().

if ($userAgent->hasFeature('mp3') && $userAgent->getFeature('mp3')) {
    // embed HTML5 audio tag...
}

Configuration Options

UserAgent Options

The following options may be passed to the constructor or within your application configuration. A "." indicates another layer of depth in the configuration array.

Each features adapter has its own options available as well, which may be mixed in with the general UserAgent options.

browser_type

Used to seed the list of devices the component will search. See also identification_sequence; this value will be prepended to that list during user agent device discovery.

http_accept

The value of the Accept HTTP header; used by some user agents to determine capabilities. Set this to seed the value explicitly.

identification_sequence

A comma-separated list of device types to scan for matches; defaults to "mobile,desktop".

storage.adapter

The name of a storage adapter used to persist the device capabilities, typically within a given user session. The value may either be a fully qualified class name, or a short name to resolve by the plugin loader for storage classes. By default, uses "Session" as the value, resolving to Zend_Http_UserAgent_Storage_Session.

storage.options[]

An array of options to pass to the constructor of a storage adapter. By default, the option browser_type will be present.

plugin_loader.[type] = [class]

Plugin loader configuration; allows you to specify a pre-configured Zend_Loader_PluginLoader extension class to use for one of the plugin loader types managed by UserAgent (currently "storage" and "device".

server[]

Typically, you will not set this; this simply allows injection of the $_SERVER superglobal (or a filtered version of it). The value should be an associative array.

user_agent

The actual HTTP User-Agent string you wish to try and match. Typically, this will be auto-discovered from the server array.

[browser_type].device.classname

The device class to use for a given browser type; typically, browser_type will be one of the supported browser devices, including:

Bot
Checker
Console
Desktop
Email
Feed
Mobile
Offline
Probe
Spam
Text
Validator

The browser_type should be normalized to lowercase for configuration purposes.

[browser_type].device.path and [browser_type].device.prefix

An alternate way to specify the device class for a given browser type is to assume it is named after the device, and that all device classes are in the same path sharing the same prefix. Configure the prefix and path using these keys.

As an example, the following would look for a class named "Mobile_Device_Bot" on the path "Mobile/Device/" under the application library.

resources.useragent.bot.device.path = APPLICATION_PATH '/../library/Mobile/Device"
resources.useragent.bot.device.prefix = "Mobile_Device"

[browser_type].features.path and [browser_type].features.classname

These settings are used to load the features capabilities detection class for a given browser type. The class will be named using the classname key, and is expected to exist in the file denoted by the path key. The class should implement Zend_Http_UserAgent_Features_Adapter.

Available Methods

__construct( $options = null );

The constructor attempts to determine the current User-Agent based on the options provided, the current request information, and/or previously discovered information persisted in storage. Once instantiated, the detected device is immediately available.

Please see configuration options section for details on the $options array.

serialize( );

Defined by the Serializable interface, this method performs logic necessary to determine what within the object should be serialized when the object is serialized by a storage adapter.

unserialize( $serialized );

Defined by the Serializable interface, this method performs logic necessary to determine how to unserialize a previously serialized instance.

setOptions( $options );

Initializes object state. Please see the configuration options section for information on the $options array.

getUserAgent( );

Retrieve the discovered User-Agent string. Unless set explicitly, this will be autodiscovered from the server array.

setUserAgent( $userAgent );

Set the User-Agent string explicitly. Once getDevice() has been called, this property is marked immutable, and calling this method will raise an exception.

getHttpAccept( $httpAccept = null );

Retrieve the HTTP Accept header value.

setHttpAccept( $httpAccept );

Explicitly set the HTTP Accept header value. Once getDevice() has been called, this property is marked immutable, and calling this method will raise an exception.

getStorage( $browser = null );

Retrieves a persistent storage object for a given browser type.

setStorage( Zend_Http_UserAgent_Storage $storage );

Use this to explicitly set the peristent storage object. Once getDevice() has been called, the storage is marked immutable (as in: you may not inject a new storage object), and calling this method will raise an exception.

clearStorage( $browser = null );

Clears any information in the persistent storage object.

getConfig( );

Retrieve configuration parameters.

getDevice( );

Use this method to get the User-Agent Device object; this is the object that will contain the various discovered device capabilities.

Discovery of the User-Agent device occurs in this method. Once the device has been retrieved, the server array, browser type, user agent, http accept, and storage properties are marked as immutable.

getBrowserType( );

Retrieve the discovered browser type; usually one of:

Bot
Checker
Console
Desktop
Email
Feed
Mobile
Offline
Probe
Spam
Text
Validator

Unless explicitly set, the browser type is unknown until getDevice() has been called.

setBrowserType( $browserType );

Explicitly set the browser type to prepend to the identification sequence. Once getDevice() has been called, the browser type is marked immutable, and calling this method will raise an exception.

getServer( );

Retrieve the array of HTTP headers and environment variables used to perform device discovery. If the array has not yet been set, it is seeded with the $_SERVER superglobal.

setServer( $server );

Explicitly set the "server" array of HTTP headers and environment variables to use during device discovery. Once getDevice() has been called, the server array is marked immutable, and calling this method will raise an exception.

getServerValue( $key );

Retrieve a single value from the server array by key.

setServerValue( $key, $value );

Overwrite or define a value in the internal server array. Once getDevice() has been called, the server array is marked immutable, and calling this method will raise an exception.

setPluginLoader( $type, $loader );

$type may be one of "device" or "storage; the former is used when attempting to find device classes, the latter for finding storage classes. $loader may be a Zend_Loader_PluginLoader instance, or a string name containing the classname of a Zend_Loader_PluginLoader extension class.

getPluginLoader( $type );

Retrieves either the "device" or "storage" plugin loader instance.

Examples

Please see the quick start for examples at this time.