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_Wurfl consumes the WURFL (Wireless Universal Resource File) PHP API. This database is considered one of the most comprehensive mobile device capabilities databases available. 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. First, you will need to download the following: The WURFL PHP API. This archive contains the most recent wurfl-latest.xml file and patches which constitute the actual WURFL database. We suggest that you inflate this archive in your "library" directory. Inflating the archive will create a wurfl-php-1.1 directory. Next, create a data and cache directory for the WURFL database and related cache files; this should be done from your project root (the directory containing the application and library directories). When you do so, make sure the directory is at least writable by the web server user; the following makes it writable for all users. Now, copy the WURFL data from the inflated archive into your data directory. Create a WURFL configuration file named application/configs/wurfl-config.php, with the following contents: Finally, edit your application.ini to add the following lines to your [production] section: The trailing directory separator on the wurfl_lib_dir setting is important. The WURFL API does no normalization, and expects it to be there. At this point, everything is setup. The first request (from a mobile device) will populate the WURFL cache by parsing the resources/wurfl.xml file, and as such may take up to a minute. After that, lookups will be quite fast, and 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. getParam('bootstrap'); $userAgent = $bootstrap->getResource('useragent'); ]]> From your action controller, use getInvokeArg() to grab the bootstrap, and from there, the user agent object. getInvokeArg('bootstrap'); $userAgent = $bootstrap->getResource('useragent'); ]]> Within your view, you can grab it using the UserAgent view helper. 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. getDevice()->getPhysicalScreenWidth(); switch (true) { case ($width <= 128): $layout->setLayout('layout-poor'); break; case ($width <= 176): $layout->setLayout('layout-medium'); break; case ($width <= 240): $layout->setLayout('layout-high'); break; case ($width <= 320): $layout->setLayout('layout-ultra'); break; default: // use default 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. hasFeature('mp3') && $userAgent->getFeature('mp3')) { // embed HTML5 audio tag... } ]]> The following options may be passed to the constructor or within your application configuration. A "." indicates another layer of depth in the configuration array; as an example, assigning "wurflapi.wurfl_config_array.wurfl.main-file" as part of a PHP configuration would require the following definition: array( 'wurfl_config_array' => array( 'wurfl' => array( 'main-file' => 'path/to/some/file', ), ), ), ); ]]> 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. [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. wurflapi.wurfl_api_version If using the WURFL API, use this key to specify which version you are using; typically, this will be either "1.0" or "1.1". wurflapi.wurfl_lib_dir If using the WURFL API, use this key to specify in which directory the library exists. wurflapi.wurfl_config_file If using the WURFL API, use this key to specify the location of the configuration file you will use; typically, this will be resources/wurfl-config.php within the wurfl_lib_dir. wurflapi.wurfl_config_array.wurfl.main-file If using version 1.1 of the WURFL API, you can omit using a wurfl_config_file, and instead provide an associative array of configuration values. This particular value indicates the location of the wurfl.xml file containing the actual WURFL database. wurflapi.wurfl_config_array.wurfl.patches[] If using version 1.1 of the WURFL API, you can omit using a wurfl_config_file, and instead provide an associative array of configuration values. This particular value is an array of file locations containing patchfiles for the wurfl.main-file (which are used to ammend and extend the primary database file). wurflapi.wurfl_config_array.persistence.provider If using version 1.1 of the WURFL API, you can omit using a wurfl_config_file, and instead provide an associative array of configuration values. This particular value indicates the type of persistence provider used when caching discovered capabilities. See the WURFL documentation for potential values; "file" is a known good value. wurflapi.wurfl_config_array.persistence.dir If using version 1.1 of the WURFL API, you can omit using a wurfl_config_file, and instead provide an associative array of configuration values. This particular value indicates the location where the persistence provider will cache discovered capabilities. __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. Please see the quick start for examples at this time.