Added Browscap adapter for Zend_Http_UserAgent

- Provides Browscap device feature capabilities adapter
- Includes tests of basic functionality
- Includes documentation, including a quick start for usage

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@24693 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/manual.xml.in

@@ -1144,6 +1144,11 @@
                     <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features.xml" />
                 </xi:fallback>
             </xi:include>
+            <xi:include href="module_specs/Zend_Http_UserAgent-Features_Browscap.xml">
+                <xi:fallback>
+                    <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features_Browscap.xml" />
+                </xi:fallback>
+            </xi:include>
             <xi:include href="module_specs/Zend_Http_UserAgent-Features_Wurfl.xml">
                 <xi:fallback>
                     <xi:include href="../en/module_specs/Zend_Http_UserAgent-Features_Wurfl.xml" />

documentation/manual/en/module_specs/Zend_Http_UserAgent-Features_Browscap.xml

@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect1 id="zend.http.user-agent-features-browscap">
+    <title>The Browscap UserAgent Features Adapter</title>
+
+    <sect2 id="zend.http.user-agent-features-browscap.intro">
+        <title>Overview</title>
+
+        <para>
+            <ulink url="http://browsers.garykeith.com/">Browscap</ulink> is an open project
+            dedicated to collecting an disseminating a "database" of browser capabilities --
+            actually a set of different files describing browser capablities. PHP has built-in
+            support for using these files via the <ulink
+                url="http://php.net/get_browser"><function>get_browser()</function></ulink>
+            function. This function requires that your <filename>php.ini</filename> provides a
+            <varname>browscap</varname> entry pointing to the PHP-specific
+            <filename>php_browscap.ini</filename> file, which <ulink
+                url="http://browsers.garykeith.com/stream.asp?PHP_BrowsCapINI">you can download from
+                the browscap site</ulink>.
+        </para>
+
+        <para>
+            This class provides a <link linkend="zend.http.user-agent-features">features
+                adapter</link> that calls <function>get_browser()</function> in order to discover
+            mobile device capabilities to inject into <classname>UserAgent</classname> device
+            instances.
+        </para>
+
+        <note id="zend.http.user-agent-features-browscap.intro.browscap-usage">
+            <title>You may need to restart your webserver</title>
+
+            <para>
+                The <varname>browscap</varname> <filename>php.ini</filename> setting is a
+                <constant>PHP_INI_SYSTEM</constant> setting, meaning it can only be set in your
+                <filename>php.ini</filename> file or in your web server configuration. As such, you
+                may need to restart your web server after adding the entry.
+            </para>
+        </note>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-browscap.quick-start">
+        <title>Quick Start</title>
+
+        <para>
+            First, if you haven't already, <ulink
+                url="http://browsers.garykeith.com/stream.asp?PHP_BrowsCapINI">download the
+                php_browscap.ini file</ulink>, and put it somewhere your web server can access it;
+            make sure the web server has permissions to read the file. Typically, you'll place this
+            in the same location as your <filename>php.ini</filename> file.
+        </para>
+
+        <para>
+            Next, update your <filename>php.ini</filename> file to add the following line:
+        </para>
+
+        <programlisting language="ini"><![CDATA[
+browscap = /path/to/php_browscap.ini
+]]></programlisting>
+
+        <note>
+            <title>Keep it simple</title>
+
+            <para>
+                If you put your <filename>php_browscap.ini</filename> file next to the
+                <filename>php.ini</filename> file, you can omit the path information, and simply
+                specify the filename.
+            </para>
+        </note>
+
+        <para>
+            Next, simply provide configuration to your application as follows:
+        </para>
+
+        <programlisting language="ini"><![CDATA[
+resources.useragent.mobile.features.classname = "Zend_Http_UserAgent_Device_Features_Browscap"
+]]></programlisting>
+
+        <para>
+            At this point, you're all set.  You can access the browser 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[
+$device = $userAgent->getDevice();
+
+$cssSupport    = $device->getFeature('cssversion');
+$jsSupport     = $device->getFeature('javascript');
+$cookieSupport = $device->getFeature('cookies');
+
+switch (true) {
+    case ($jsSupport && $cookieSupport && $cssSupport >= 3):
+        $layout->setLayout('layout-html5');
+        break;
+    case ($jsSupport && $cookieSupport && $cssSupport < 3):
+        $layout->setLayout('layout-xhtml');
+        break;
+    case (!$jsSupport && $cookieSupport && $cssSupport < 3):
+        $layout->setLayout('layout-html-transitional');
+        break;
+    default:
+        $layout->setLayout('layout-web-1');
+        break;
+}
+]]></programlisting>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-browscap.options">
+        <title>Configuration Options</title>
+
+        <para>
+            The browscap adapter has no configuration options.
+        </para>
+    </sect2>
+
+    <sect2 id="zend.http.user-agent-features-browscap.methods">
+        <title>Available Methods</title>
+
+        <variablelist>
+            <varlistentry id="zend.http.user-agent-features-browscap.methods.get-from-request">
+                <term>
+                    <methodsynopsis>
+                        <methodname>getFromRequest</methodname>
+                        <methodparam>
+                            <funcparams>array $request, array $config</funcparams>
+                        </methodparam>
+                    </methodsynopsis>
+                </term>
+
+                <listitem>
+                    <para>
+                        Decompose the request in order to return an array of device capabilities.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </sect2>
+</sect1>

documentation/manual/en/module_specs/Zend_Http_UserAgent.xml

@@ -82,6 +82,17 @@
             <listitem>
                 <para>
                     <link
+                        linkend="zend.http.user-agent-features-browscap">Zend_Http_UserAgent_Features_Adapter_Browscap</link>
+                    utilizes PHP's native <ulink url="http://php.net/get_browser"><function>get_browser()</function></ulink>
+                    in conjunction with <ulink url="http://browsers.garykeith.com/">browscap</ulink>.
+                    While the database featureset is not as fine-grained as other projects, for the
+                    majority of purposes, it provides reliable, fast results.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <link
                         linkend="zend.http.user-agent-features-wurfl">Zend_Http_UserAgent_Features_Adapter_Wurfl</link>
                     consumes the <ulink url="http://wurfl.sourceforge.net/">WURFL</ulink> (Wireless
                     Universal Resource File) PHP API. This database is considered one of the most

library/Zend/Http/UserAgent/Features/Adapter/Browscap.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Http
+ * @subpackage UserAgent
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+/**
+ * Zend_Http_UserAgent_Features_Adapter_Interface
+ */
+require_once 'Zend/Http/UserAgent/Features/Adapter.php';
+
+/**
+ * Features adapter utilizing PHP's native browscap support
+ *
+ * Requires that you have a PHP-compatible version of the browscap.ini, per the
+ * instructions at http://php.net/get_browser
+ *
+ * @package    Zend_Http
+ * @subpackage UserAgent
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_Http_UserAgent_Features_Adapter_Browscap implements Zend_Http_UserAgent_Features_Adapter
+{
+    /**
+     * Constructor
+     *
+     * Validate that we have browscap support available.
+     * 
+     * @return void
+     * @throws Zend_Http_UserAgent_Features_Exception
+     */
+    public function __construct()
+    {
+        $browscap = ini_get('browscap');
+        if (empty($browscap) || !file_exists($browscap)) {
+            require_once 'Zend/Http/UserAgent/Features/Exception.php';
+            throw new Zend_Http_UserAgent_Features_Exception(sprintf(
+                '%s requires a browscap entry in php.ini pointing to a valid browscap.ini; none present',
+                __CLASS__
+            ));
+        }
+    }
+
+    /**
+     * Get features from request
+     *
+     * @param  array $request $_SERVER variable
+     * @param  array $config ignored; included only to satisfy parent class
+     * @return array
+     */
+    public static function getFromRequest($request, array $config)
+    {
+        $browscap = get_browser($request['http_user_agent'], true);
+        $features = array();
+        foreach ($browscap as $key => $value) {
+            // For a few keys, we need to munge a bit for the device object
+            switch ($key) {
+                case 'browser':
+                    $features['mobile_browser'] = $value;
+                    break;
+                case 'version':
+                    $features['mobile_browser_version'] = $value;
+                    break;
+                case 'platform':
+                    $features['device_os'] = $value;
+                    break;
+                default:
+                    $features[$key] = $value;
+                    break;
+            }
+        }
+        return $features;
+    }
+}

tests/Zend/Http/UserAgent/AllTests.php

@@ -26,6 +26,7 @@ if (!defined('PHPUnit_MAIN_METHOD')) {
 
 require_once 'Zend/Http/UserAgentTest.php';
 require_once 'Zend/Http/UserAgent/AbstractDeviceTest.php';
+require_once 'Zend/Http/UserAgent/Features/Adapter/BrowscapTest.php';
 require_once 'Zend/Http/UserAgent/Features/Adapter/WurflApiTest.php';
 
 /**
@@ -49,6 +50,7 @@ class Zend_Http_UserAgent_AllTests
 
         $suite->addTestSuite('Zend_Http_UserAgentTest');
         $suite->addTestSuite('Zend_Http_UserAgent_AbstractDeviceTest');
+        $suite->addTestSuite('Zend_Http_UserAgent_Features_Adapter_BrowscapTest');
         $suite->addTestSuite('Zend_Http_UserAgent_Features_Adapter_WurflApiTest');
 
         return $suite;

tests/Zend/Http/UserAgent/Features/Adapter/BrowscapTest.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Http_UserAgent
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+if (!defined('PHPUnit_MAIN_METHOD')) {
+    define('PHPUnit_MAIN_METHOD', 'Zend_Http_UserAgent_Features_Adapter_Browscap::main');
+}
+
+require_once 'Zend/Http/UserAgent/Features/Adapter/Browscap.php';
+
+/**
+ * @category   Zend
+ * @package    Zend_Http_UserAgent
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_Http_UserAgent_Features_Adapter_BrowscapTest extends PHPUnit_Framework_TestCase
+{
+    public static function main()
+    {
+        $suite  = new PHPUnit_Framework_TestSuite(__CLASS__);
+        $result = PHPUnit_TextUI_TestRunner::run($suite);
+    }
+
+    public function setUp()
+    {
+        $browscap = ini_get('browscap');
+        if (empty($browscap) || !file_exists($browscap)) {
+            $this->markTestSkipped('Requires php.ini to provide a valid "browscap" entry');
+        }
+    }
+
+    public function testGetFromRequest()
+    {
+        $request['http_user_agent'] = 'Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420.1 (KHTML, like Gecko) Version/3.0 Mobile/4A102 Safari/419.3';
+        $adapter = Zend_Http_UserAgent_Features_Adapter_Browscap::getFromRequest($request, array());
+        $this->assertEquals(1,                           $adapter['ismobiledevice']);
+        $this->assertEquals(1,                           $adapter['javascript']);
+        $this->assertEquals(3,                           $adapter['cssversion']);
+        $this->assertEquals('iPhone',                    $adapter['mobile_browser']);
+        $this->assertContains('^mozilla/.\\..*(iphone;.*cpu', $adapter['browser_name_regex']);
+
+        $request['http_user_agent'] = 'SonyEricssonK700i/R2AC SEMC-Browser/4.0.2 Profile/MIDP-2.0 Configuration/CLDC-1.1';
+        $adapter = Zend_Http_UserAgent_Features_Adapter_Browscap::getFromRequest($request, array());
+        $this->assertEquals(1,                           $adapter['ismobiledevice']);
+        $this->assertEquals(1,                           $adapter['javascript']);
+        $this->assertEquals(1,                           $adapter['cssversion']);
+        $this->assertEquals('SEMC Browser',              $adapter['mobile_browser']);
+        $this->assertEquals('^.*semc-browser/.*$',       $adapter['browser_name_regex']);
+    }
+}
+
+if (PHPUnit_MAIN_METHOD == 'Zend_Http_UserAgent_Features_Adapter_Browscap::main') {
+    Zend_Http_UserAgent_Features_Adapter_Browscap::main();
+}