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