repo_zf1/documentation/manual/en/module_specs/Zend_Http_UserAgent.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.http.user-agent">
    <title>Zend_Http_UserAgent</title>

    <sect2 id="zend.http.user-agent.intro">
        <title>Overview</title>

        <para>
            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.
        </para>

        <para>
            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. <classname>Zend_Http_UserAgent</classname> was created to provide these
            capabilities for your applications. It consists of several major features:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    The primary <classname>Zend_Http_UserAgent</classname> class, which detects the
                    User Agent, and gives you a device object, as well as persists the device object
                    for later retrieval.
                </para>
            </listitem>

            <listitem>
                <para>
                    A <link linkend="zend.http.user-agent-device">Zend_Http_UserAgent_Device</link>
                    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.
                </para>
            </listitem>

            <listitem>
                <para>
                    A <link linkend="zend.http.user-agent-features">Zend_Http_UserAgent_Features_Adapter</link>
                    interface; concrete implementations provide the ability to discover device
                    capabilities, or features.
                </para>
            </listitem>

            <listitem>
                <para>
                    A <link linkend="zend.http.user-agent-storage">Zend_Http_UserAgent_Storage</link>
                    interface, which is used to persist discovered devices for given users, allowing
                    for faster device capability discovery on subsequent page visits.
                </para>
            </listitem>

            <listitem>
                <para>
                    A <link linkend="zend.view.helpers.initial.user-agent">view helper</link> that
                    can be used within your view scripts and layouts to branch display logic based
                    on device capabilities.
                </para>
            </listitem>

            <listitem>
                <para>
                    A <classname>Zend_Application</classname> <link
                        linkend="zend.application.available-resources.useragent">resource</link> for
                    configuring and instantiating the user agent object, as well as seeding the view
                    helper with the user agent object instance.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            At the time of this writing, The <classname>UserAgent</classname> component provides
            only a single features adapter, one that consumes the <ulink
                url="http://wurfl.sourceforge.net/">WURFL</ulink> (Wireless Universal Resource File)
            PHP API. This database is considered one of the most comprehensive mobile device
            databases, and coupled with the <classname>UserAgent</classname> component can provide
            you with all the tools you need to write applications targetting mobile devices with
            Zend Framework.
        </para>
    </sect2>

    <sect2 id="zend.http.user-agent.quick-start">
        <title>Quick Start</title>

        <para>
            First, you will need to download the following:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    The <acronym>WURFL</acronym> <ulink
                        url="http://sourceforge.net/projects/wurfl/files/WURFL%20PHP/1.1/wurfl-php-1.1.tar.gz/download">PHP
                        API</ulink>. This includes the <filename>wurfl.xml</filename> file, which is
                    the actual <acronym>WURFL</acronym> database.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            We suggest that you place this library in your "library" directory. Inflating the
            archive will create a <filename>Wurfl/1.1/</filename> directory.
        </para>

        <programlisting language="text">
project
|-- application
|-- data
|-- library
|   |-- Wurfl
|   |   |-- 1.1
|   |   |   |-- resources
|   |   |       |-- wurfl.xml
|   |   |       `-- wurfl-config.php
</programlisting>

        <para>
            Next, find the file <filename>resources/wurfl-config.php</filename> in your
            <acronym>WURFL</acronym> library. The <acronym>WURFL</acronym> PHP API is designed to
            cache data. As such, you will want to set the <varname>['persistence']['dir']</varname>
            key. We recommend having these point to <filename>APPLICATION_PATH .
                "/../data/wurfl/</filename>; you will need to create this directory if it does not
            yet.
        </para>

        <programlisting language="php"><![CDATA[
$configuration['persistence']['dir'] = APPLICATION_PATH . '/../data/wurfl';
]]></programlisting>

        <para>
            Now, in your <filename>application.ini</filename>, add the following entries:
        </para>

        <programlisting language="ini">
resources.useragent.wurflapi.wurfl_api_version = "1.1"
resources.useragent.wurflapi.wurfl_lib_dir = APPLICATION_PATH "/../library/Wurfl/1.1"
resources.useragent.wurflapi.wurfl_config_file = APPLICATION_PATH "/../library/Wurfl/1.1/resources/wurfl-config.php"
</programlisting>

        <para>
            At this point, everything is setup. The first request will populate the
            <acronym>WURFL</acronym> cache by parsing the <filename>resources/wurfl.xml</filename>
            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.
        </para>

        <para>
            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.
        </para>

        <programlisting language="php"><![CDATA[
$bootstrap = Zend_Controller_Front::getInstance()->getParam('bootstrap');
$userAgent = $bootstrap->getResource('useragent');
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
$bootstrap = $this->getInvokeArg('bootstrap');
$userAgent = $bootstrap->getResource('useragent');
]]></programlisting>

        <para>
            Within your view, you can grab it using the <classname>UserAgent</classname> view
            helper.
        </para>

        <programlisting language="php"><![CDATA[
$userAgent = $this->userAgent();
]]></programlisting>

        <para>
            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.
        </para>

        <programlisting language="php"><![CDATA[
$width = $userAgent->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;
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.http.user-agent.options">
        <title>Configuration Options</title>

        <variablelist>
            <title>UserAgent Options</title>

            <para>
                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:
            </para>

            <programlisting language="php"><![CDATA[
$config = array(
    'wurflapi' => array(
        'wurfl_config_array' => array(
            'wurfl' => array(
                'main-file' => 'path/to/some/file',
            ),
        ),
    ),
);
]]></programlisting>

            <varlistentry>
                <term>browser_type</term>

                <listitem>
                    <para>
                        Used to seed the list of devices the component will search. See also
                        <varname>identification_sequence</varname>; this value will be prepended to
                        that list during user agent device discovery.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>http_accept</term>

                <listitem>
                    <para>
                        The value of the <varname>Accept</varname> <acronym>HTTP</acronym> header;
                        used by some user agents to determine capabilities. Set this to seed the
                        value explicitly.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>identification_sequence</term>

                <listitem>
                    <para>
                        A comma-separated list of device types to scan for matches; defaults to
                        "mobile,desktop".
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>storage.adapter</term>

                <listitem>
                    <para>
                        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
                        <classname>Zend_Http_UserAgent_Storage_Session</classname>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>storage.options[]</term>

                <listitem>
                    <para>
                        An array of options to pass to the constructor of a storage adapter. By
                        default, the option <varname>browser_type</varname> will be present.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>plugin_loader.[type] = [class]</term>

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

            <varlistentry>
                <term>server[]</term>

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

            <varlistentry>
                <term>user_agent</term>

                <listitem>
                    <para>
                        The actual <acronym>HTTP</acronym> User-Agent string you wish to try and
                        match. Typically, this will be auto-discovered from the
                        <varname>server</varname> array.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>[browser_type].device.classname</term>

                <listitem>
                    <para>
                        The device class to use for a given browser type; typically,
                        <varname>browser_type</varname> will be one of the supported browser
                        devices, including:
                    </para>

                    <itemizedlist>
                        <listitem><para>Bot</para></listitem>
                        <listitem><para>Checker</para></listitem>
                        <listitem><para>Console</para></listitem>
                        <listitem><para>Desktop</para></listitem>
                        <listitem><para>Email</para></listitem>
                        <listitem><para>Feed</para></listitem>
                        <listitem><para>Mobile</para></listitem>
                        <listitem><para>Offline</para></listitem>
                        <listitem><para>Probe</para></listitem>
                        <listitem><para>Spam</para></listitem>
                        <listitem><para>Text</para></listitem>
                        <listitem><para>Validator</para></listitem>
                    </itemizedlist>

                    <para>
                        The <varname>browser_type</varname> should be normalized to lowercase for
                        configuration purposes.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>[browser_type].device.path and [browser_type].device.prefix</term>

                <listitem>
                    <para>
                        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.
                    </para>

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

                    <programlisting language="ini">
resources.useragent.bot.device.path = APPLICATION_PATH '/../library/Mobile/Device"
resources.useragent.bot.device.prefix = "Mobile_Device"
</programlisting>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>[browser_type].features.path and [browser_type].features.classname</term>

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

            <varlistentry>
                <term>wurflapi.wurfl_api_version</term>

                <listitem>
                    <para>
                        If using the <acronym>WURFL</acronym> API, use this key to specify which
                        version you are using; typically, this will be either "1.0" or "1.1".
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_lib_dir</term>

                <listitem>
                    <para>
                        If using the <acronym>WURFL</acronym> API, use this key to specify in which
                        directory the library exists.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_config_file</term>

                <listitem>
                    <para>
                        If using the <acronym>WURFL</acronym> API, use this key to specify the
                        location of the configuration file you will use; typically, this will be
                        <filename>resources/wurfl-config.php</filename> within the
                        <varname>wurfl_lib_dir</varname>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_config_array.wurfl.main-file</term>

                <listitem>
                    <para>
                        If using version 1.1 of the <acronym>WURFL</acronym> API, you can omit using
                        a <varname>wurfl_config_file</varname>, and instead provide an associative
                        array of configuration values. This particular value indicates the location
                        of the <filename>wurfl.xml</filename> file containing the actual
                        <acronym>WURFL</acronym> database.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_config_array.wurfl.patches[]</term>

                <listitem>
                    <para>
                        If using version 1.1 of the <acronym>WURFL</acronym> API, you can omit using
                        a <varname>wurfl_config_file</varname>, and instead provide an associative
                        array of configuration values. This particular value is an array of file
                        locations containing patchfiles for the <varname>wurfl.main-file</varname>
                        (which are used to ammend and extend the primary database file).
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_config_array.persistence.provider</term>

                <listitem>
                    <para>
                        If using version 1.1 of the <acronym>WURFL</acronym> API, you can omit using
                        a <varname>wurfl_config_file</varname>, 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
                        <acronym>WURFL</acronym> documentation for potential values; "file" is a
                        known good value.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>wurflapi.wurfl_config_array.persistence.dir</term>

                <listitem>
                    <para>
                        If using version 1.1 of the <acronym>WURFL</acronym> API, you can omit using
                        a <varname>wurfl_config_file</varname>, and instead provide an associative
                        array of configuration values. This particular value indicates the location
                        where the persistence provider will cache discovered capabilities.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.http.user-agent.methods">
        <title>Available Methods</title>
        <refentry id="zend.http.user-agent.methods.constructor">
            <refnamediv>
                <refname>__construct</refname>
                <refpurpose>Instantiate and initialize</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>__construct</methodname>
                    <methodparam>
                        <funcparams>$options = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>__construct()</title>

                <para>
                    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.
                </para>

                <para>
                    Please see <link linkend="zend.http.user-agent.options">configuration
                        options</link> section for details on the <varname>$options</varname> array.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.serialize">
            <refnamediv>
                <refname>serialize</refname>
                <refpurpose>Serialize the object for persistence</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>serialize</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>serialize()</title>

                <para>
                    Defined by the <interfacename>Serializable</interfacename> interface, this
                    method performs logic necessary to determine what within the object should be
                    serialized when the object is serialized by a storage adapter.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.unserialize">
            <refnamediv>
                <refname>unserialize</refname>
                <refpurpose>Unserialize the object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>unserialize</methodname>
                    <methodparam>
                        <funcparams>$serialized</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>unserialize()</title>

                <para>
                    Defined by the <interfacename>Serializable</interfacename> interface, this
                    method performs logic necessary to determine how to unserialize a previously
                    serialized instance.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-options">
            <refnamediv>
                <refname>setOptions</refname>
                <refpurpose>Initialize object state</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setOptions</methodname>
                    <methodparam>
                        <funcparams>$options</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setOptions()</title>

                <para>
                    Initializes object state. Please see the <link
                        linkend="zend.http.user-agent.options">configuration options</link> section
                    for information on the <varname>$options</varname> array.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.get-user-agent">
            <refnamediv>
                <refname>getUserAgent</refname>
                <refpurpose>Get the user agent string</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getUserAgent</methodname>
                    <methodparam>
                        <funcparams></funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getUserAgent()</title>

                <para>
                    Retrieve the discovered User-Agent string. Unless set explicitly, this will be
                    autodiscovered from the server array.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-user-agent">
            <refnamediv>
                <refname>setUserAgent</refname>
                <refpurpose>Set the user agent string</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setUserAgent</methodname>
                    <methodparam>
                        <funcparams>$userAgent</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setUserAgent()</title>

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

        <refentry id="zend.http.user-agent.methods.get-http-accept">
            <refnamediv>
                <refname>getHttpAccept</refname>
                <refpurpose>Get the HTTP Accept header value</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getHttpAccept</methodname>
                    <methodparam>
                        <funcparams>$httpAccept = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getHttpAccept()</title>

                <para>
                    Retrieve the HTTP Accept header value. 
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-http-accept">
            <refnamediv>
                <refname>setHttpAccept</refname>
                <refpurpose>Set the HTTP Accept header value</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setHttpAccept</methodname>
                    <methodparam>
                        <funcparams>$httpAccept</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setHttpAccept()</title>

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

        <refentry id="zend.http.user-agent.methods.get-storage">
            <refnamediv>
                <refname>getStorage</refname>
                <refpurpose>Get the persistent storage object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getStorage</methodname>
                    <methodparam>
                        <funcparams>$browser = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getStorage()</title>

                <para>
                    Retrieves a persistent storage object for a given browser type.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-storage">
            <refnamediv>
                <refname>setStorage</refname>
                <refpurpose>Set the persistent storage object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setStorage</methodname>
                    <methodparam>
                        <funcparams>Zend_Http_UserAgent_Storage $storage</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setStorage()</title>

                <para>
                    Use this to explicitly set the peristent storage object. Once
                    <methodname>getDevice()</methodname> 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.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.clear-storage">
            <refnamediv>
                <refname>clearStorage</refname>
                <refpurpose>Clear the storage object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>clearStorage</methodname>
                    <methodparam>
                        <funcparams>$browser = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>clearStorage()</title>

                <para>
                    Clears any information in the persistent storage object.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.get-config">
            <refnamediv>
                <refname>getConfig</refname>
                <refpurpose></refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getConfig</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getConfig()</title>

                <para>
                    Retrieve configuration parameters.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.get-device">
            <refnamediv>
                <refname>getDevice</refname>
                <refpurpose>Get the device object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getDevice</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getDevice()</title>

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

                <para>
                    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.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.get-browser-type">
            <refnamediv>
                <refname>getBrowserType</refname>
                <refpurpose></refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getBrowserType</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getBrowserType()</title>

                <para>
                    Retrieve the discovered browser type; usually one of:
                </para>

                <itemizedlist>
                    <listitem><para>Bot</para></listitem>
                    <listitem><para>Checker</para></listitem>
                    <listitem><para>Console</para></listitem>
                    <listitem><para>Desktop</para></listitem>
                    <listitem><para>Email</para></listitem>
                    <listitem><para>Feed</para></listitem>
                    <listitem><para>Mobile</para></listitem>
                    <listitem><para>Offline</para></listitem>
                    <listitem><para>Probe</para></listitem>
                    <listitem><para>Spam</para></listitem>
                    <listitem><para>Text</para></listitem>
                    <listitem><para>Validator</para></listitem>
                </itemizedlist>

                <para>
                    Unless explicitly set, the browser type is unknown until
                    <methodname>getDevice()</methodname> has been called.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-browser-type">
            <refnamediv>
                <refname>setBrowserType</refname>
                <refpurpose>Set a browser type to prepend to the identification sequence</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setBrowserType</methodname>
                    <methodparam>
                        <funcparams>$browserType</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setBrowserType()</title>

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

        <refentry id="zend.http.user-agent.methods.get-server">
            <refnamediv>
                <refname>getServer</refname>
                <refpurpose>Retrieve the server array</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getServer</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getServer()</title>

                <para>
                    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
                    <varname>$_SERVER</varname> superglobal.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-server">
            <refnamediv>
                <refname>setServer</refname>
                <refpurpose>Set the server array</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setServer</methodname>
                    <methodparam>
                        <funcparams>$server</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setServer()</title>

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

        <refentry id="zend.http.user-agent.methods.get-server-value">
            <refnamediv>
                <refname>getServerValue</refname>
                <refpurpose></refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getServerValue</methodname>
                    <methodparam>
                        <funcparams>$key</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getServerValue()</title>

                <para>
                    Retrieve a single value from the server array by key.
                </para>
            </refsect1>
        </refentry>

        <refentry id="zend.http.user-agent.methods.set-server-value">
            <refnamediv>
                <refname>setServerValue</refname>
                <refpurpose></refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setServerValue</methodname>
                    <methodparam>
                        <funcparams>$key, $value</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setServerValue()</title>

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

        <refentry id="zend.http.user-agent.methods.set-plugin-loader">
            <refnamediv>
                <refname>setPluginLoader</refname>
                <refpurpose>Set a specific plugin loader instance</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setPluginLoader</methodname>
                    <methodparam>
                        <funcparams>$type, $loader</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>setPluginLoader()</title>

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

        <refentry id="zend.http.user-agent.methods.get-plugin-loader">
            <refnamediv>
                <refname>getPluginLoader</refname>
                <refpurpose>Retrieve a plugin loader</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getPluginLoader</methodname>
                    <methodparam>
                        <funcparams>$type</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsect1>
                <title>getPluginLoader()</title>

                <para>
                    Retrieves either the "device" or "storage" plugin loader instance.
                </para>
            </refsect1>
        </refentry>
    </sect2>

    <sect2 id="zend.http.user-agent.examples">
        <title>Examples</title>

        <para>
            Please see the <link linkend="zend.http.user-agent.quick-start">quick start</link> for
            examples at this time.
        </para>
    </sect2>
</sect1>