[PROMOTE] Zend_View_Helper_Currency

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

documentation/manual/en/module_specs/Zend_View-Helpers-Currency.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect3 id="zend.view.helpers.initial.currency">
+    <title>Currency Helper</title>
+
+    <para>
+        Displaying localized currency values is a common task; the
+        <classname>Zend_Currency</classname> view helper is intended to simply this task.  See the
+        <link linkend="zend.currency.introduction">Zend Currency documentation</link> for specifics
+        on this localization feature. In this section, we will focus simply on usage of the view
+        helper.
+    </para>
+
+    <para>
+        There are several ways to initiate the <emphasis>Currency</emphasis> view helper:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>
+                Registered, through a previously registered instance in
+                <classname>Zend_Registry</classname>.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Afterwards, through the fluent interface.
+            </para>
+        </listitem>
+
+        <listitem>
+            <para>
+                Directly, through instantiating the class.
+            </para>
+        </listitem>
+    </itemizedlist>
+
+    <para>
+        A registered instance of <classname>Zend_Currency</classname> is the preferred usage for
+        this helper. Doing so, you can select the currency to be used prior to adding the adapter to
+        the registry.
+    </para>
+
+    <para>
+        There are several ways to select the desired currency. First, you may simply provide a
+        currency string; alternately, you may specify a locale.  The preferred way is to use a
+        locale as this information is automatically detected and selected via the HTTP client
+        headers provided when a user accesses your application, and ensures the currency provided
+        will match their locale.
+    </para>
+
+    <note>
+        <para>
+            We are speaking of "locales" instead of "languages" because a language may vary based on
+            the geographical region in which it is used. For example, English is spoken in different
+            dialects: British English, American English, etc. As a currency always correlates to a
+            country you must give a fully-qualified locale, which means providing both the language
+            <emphasis>and</emphasis> region. Therefore, we say "locale" instead of "language."
+        </para>
+    </note>
+
+    <example id="zend.view.helpers.initial.currency.registered">
+        <title>Registered instance</title>
+
+        <para>
+            To use a registered instance, simply create an instance of
+            <classname>Zend_Currency</classname> and register it within
+            <classname>Zend_Registry</classname> using <classname>Zend_Currency</classname> as its
+            key.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// our example currency
+$currency = new Zend_Currency('de_AT');
+Zend_Registry::set('Zend_Currency', $currency);
+
+// within your view
+echo $this->currency(1234.56);
+// this returns '€ 1.234,56'
+]]></programlisting>
+    </example>
+
+    <para>
+        If you are more familiar with the fluent interface, then you can also create an instance
+        within your view and configure the helper afterwards.
+    </para>
+
+    <example id="zend.view.helpers.initial.currency.afterwards">
+        <title>Within the view</title>
+
+        <para>
+            To use the fluent interface, create an instance of <classname>Zend_Currency</classname>,
+            call the helper without a parameter, and call the <methodname>setCurrency()</methodname>
+            method.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// within your view
+$currency = new Zend_Currency('de_AT');
+$this->currency()->setCurrency($currency)->currency(1234.56);
+// this returns '€ 1.234,56'
+]]></programlisting>
+    </example>
+
+    <para>
+        If you are using the helper without <classname>Zend_View</classname> then you can
+        also use it directly.
+    </para>
+
+    <example id="zend.view.helpers.initial.currency.directly">
+        <title>Direct usage</title>
+
+        <programlisting language="php"><![CDATA[
+// our example currency
+$currency = new Zend_Currency('de_AT');
+
+// initiate the helper
+$helper = new Zend_View_Helper_Currency($currency);
+echo $helper->currency(1234.56); // this returns '€ 1.234,56'
+]]></programlisting>
+    </example>
+
+    <para>
+        As already seen, the <methodname>currency()</methodname> method is used to return the
+        currency string. Just call it with the value you want to display as a currency.  It also
+        accepts some options which may be used to change the behaviour and output of the helper.
+    </para>
+
+    <example id="zend.view.helpers.initial.currency.directly">
+        <title>Direct usage</title>
+
+        <programlisting language="php"><![CDATA[
+// our example currency
+$currency = new Zend_Currency('de_AT');
+
+// initiate the helper
+$helper = new Zend_View_Helper_Currency($currency);
+echo $helper->currency(1234.56); // this returns '€ 1.234,56'
+echo $helper->currency(1234.56, array('precision' => 1));
+// this returns '€ 1.234,6'
+]]></programlisting>
+    </example>
+
+    <para>
+        For details about the available options, search for <classname>Zend_Currency</classname>'s
+        <methodname>toCurrency()</methodname> method.
+    </para>
+</sect3>
+<!--
+vim:se ts=4 sw=4 et:
+-->

documentation/manual/en/module_specs/Zend_View-Helpers.xml

@@ -353,6 +353,7 @@ echo $this->formCheckbox('foo',
 
         <xi:include href="Zend_View-Helpers-Action.xml" />
         <xi:include href="Zend_View-Helpers-BaseUrl.xml" />
+        <xi:include href="Zend_View-Helpers-Currency.xml" />
         <xi:include href="Zend_View-Helpers-Cycle.xml" />
         <xi:include href="Zend_View-Helpers-Partial.xml" />
         <xi:include href="Zend_View-Helpers-Placeholder.xml" />

library/Zend/View/Helper/Currency.php

@@ -0,0 +1,119 @@
+<?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_View
+ * @subpackage Helper
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id:$
+ */
+
+/** Zend_View_Helper_Abstract.php */
+require_once 'Zend/View/Helper/Abstract.php';
+
+/**
+ * Currency view helper
+ *
+ * @category  Zend
+ * @package   Zend_View
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_View_Helper_Currency extends Zend_View_Helper_Abstract
+{
+    /**
+     * Currency object
+     *
+     * @var Zend_Currency
+     */
+    protected $_currency;
+
+    /**
+     * Constructor for manually handling
+     *
+     * @param  Zend_Currency $currency Instance of Zend_Currency
+     * @return void
+     */
+    public function __construct($currency = null)
+    {
+        if ($currency === null) {
+            require_once 'Zend/Registry.php';
+            if (Zend_Registry::isRegistered('Zend_Currency')) {
+                $currency = Zend_Registry::get('Zend_Currency');
+            }
+        }
+
+        $this->setCurrency($currency);
+    }
+
+    /**
+     * Output a formatted currency
+     *
+     * @param  integer|float                    $value    Currency value to output
+     * @param  string|Zend_Locale|Zend_Currency $currency OPTIONAL Currency to use for this call
+     * @return string Formatted currency
+     */
+    public function currency($value = null, $currency = null)
+    {
+        if ($value === null) {
+            return $this;
+        }
+
+        if (is_string($currency) || ($currency instanceof Zend_Locale)) {
+            require_once 'Zend/Locale.php';
+            if (Zend_Locale::isLocale($currency)) {
+                $currency = array('locale' => $currency);
+            }
+        }
+
+        if (is_string($currency)) {
+            $currency = array('currency' => $currency);
+        }
+
+        if (is_array($currency)) {
+            return $this->_currency->toCurrency($value, $currency);
+        }
+
+        return $this->_currency->toCurrency($value);
+    }
+
+    /**
+     * Sets a currency to use
+     *
+     * @param  Zend_Currency|String|Zend_Locale $currency Currency to use
+     * @throws Zend_View_Exception When no or a false currency was set
+     * @return Zend_View_Helper_Currency
+     */
+    public function setCurrency($currency = null)
+    {
+        if (!$currency instanceof Zend_Currency) {
+            require_once 'Zend/Currency.php';
+            $currency = new Zend_Currency($currency);
+        }
+        $this->_currency = $currency;
+
+        return $this;
+    }
+
+    /**
+     * Retrieve currency object
+     *
+     * @return Zend_Currency|null
+     */
+    public function getCurrency()
+    {
+        return $this->_currency;
+    }
+}

tests/Zend/View/Helper/AllTests.php

@@ -28,6 +28,7 @@ if (!defined('PHPUnit_MAIN_METHOD')) {
 
 require_once 'Zend/View/Helper/ActionTest.php';
 require_once 'Zend/View/Helper/BaseUrlTest.php';
+require_once 'Zend/View/Helper/CurrencyTest.php';
 require_once 'Zend/View/Helper/CycleTest.php';
 require_once 'Zend/View/Helper/DeclareVarsTest.php';
 require_once 'Zend/View/Helper/DoctypeTest.php';
@@ -95,6 +96,7 @@ class Zend_View_Helper_AllTests
 
         $suite->addTestSuite('Zend_View_Helper_ActionTest');
         $suite->addTestSuite('Zend_View_Helper_BaseUrlTest');
+        $suite->addTestSuite('Zend_View_Helper_CurrencyTest');
         $suite->addTestSuite('Zend_View_Helper_CycleTest');
         $suite->addTestSuite('Zend_View_Helper_DeclareVarsTest');
         $suite->addTestSuite('Zend_View_Helper_DoctypeTest');

tests/Zend/View/Helper/CurrencyTest.php

@@ -0,0 +1,188 @@
+<?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_View
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id: TranslateTest.php 18387 2010-09-23 21:00:00Z thomas $
+ */
+
+// Call Zend_View_Helper_CurrencyTest::main() if this source file is executed directly.
+if (!defined("PHPUnit_MAIN_METHOD")) {
+    define("PHPUnit_MAIN_METHOD", "Zend_View_Helper_CurrencyTest::main");
+}
+
+require_once dirname(__FILE__) . '/../../../TestHelper.php';
+
+/** Zend_View_Helper_Currency */
+require_once 'Zend/View/Helper/Currency.php';
+
+/** Zend_Registry */
+require_once 'Zend/Registry.php';
+
+/** Zend_Currency */
+require_once 'Zend/Currency.php';
+
+/**
+ * Test class for Zend_View_Helper_Currency
+ *
+ * @category   Zend
+ * @package    Zend_View
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @group      Zend_View
+ * @group      Zend_View_Helper
+ */
+class Zend_View_Helper_CurrencyTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * @var Zend_View_Helper_Currency
+     */
+    public $helper;
+
+    /**
+     * Runs the test methods of this class.
+     *
+     * @return void
+     */
+    public static function main()
+    {
+        require_once "PHPUnit/TextUI/TestRunner.php";
+
+        $suite  = new PHPUnit_Framework_TestSuite("Zend_View_Helper_CurrencyTest");
+        $result = PHPUnit_TextUI_TestRunner::run($suite);
+    }
+
+    public function clearRegistry()
+    {
+        $regKey = 'Zend_Currency';
+        if (Zend_Registry::isRegistered($regKey)) {
+            $registry = Zend_Registry::getInstance();
+            unset($registry[$regKey]);
+        }
+    }
+
+    /**
+     * Sets up the fixture, for example, open a network connection.
+     * This method is called before a test is executed.
+     *
+     * @return void
+     */
+    public function setUp()
+    {
+        $this->clearRegistry();
+        $this->helper = new Zend_View_Helper_Currency();
+    }
+
+    /**
+     * Tears down the fixture, for example, close a network connection.
+     * This method is called after a test is executed.
+     *
+     * @return void
+     */
+    public function tearDown()
+    {
+        unset($this->helper);
+        $this->clearRegistry();
+    }
+
+    public function testCurrencyObjectPassedToConstructor()
+    {
+        $curr = new Zend_Currency('de_AT');
+
+        $helper = new Zend_View_Helper_Currency($curr);
+        $this->assertEquals('€ 1.234,56', $helper->currency(1234.56));
+        $this->assertEquals('€ 0,12', $helper->currency(0.123));
+    }
+
+    public function testLocalCurrencyObjectUsedWhenPresent()
+    {
+        $curr = new Zend_Currency('de_AT');
+
+        $this->helper->setCurrency($curr);
+        $this->assertEquals('€ 1.234,56', $this->helper->currency(1234.56));
+        $this->assertEquals('€ 0,12', $this->helper->currency(0.123));
+    }
+
+    public function testCurrencyObjectInRegistryUsedInAbsenceOfLocalCurrencyObject()
+    {
+        $curr = new Zend_Currency('de_AT');
+        Zend_Registry::set('Zend_Currency', $curr);
+        $this->assertEquals('€ 1.234,56', $this->helper->currency(1234.56));
+    }
+
+    public function testPassingNonNullNonCurrencyObjectToConstructorThrowsException()
+    {
+        try {
+            $helper = new Zend_View_Helper_Currency('something');
+        } catch (Exception $e) {
+            $this->assertContains('not found', $e->getMessage());
+        }
+    }
+
+    public function testPassingNonCurrencyObjectToSetCurrencyThrowsException()
+    {
+        try {
+            $this->helper->setCurrency('something');
+        } catch (Exception $e) {
+            $this->assertContains('not found', $e->getMessage());
+        }
+    }
+
+    public function testCanOutputCurrencyWithOptions()
+    {
+        $curr = new Zend_Currency('de_AT');
+
+        $this->helper->setCurrency($curr);
+        $this->assertEquals("€ 1.234,56", $this->helper->currency(1234.56, "de_AT"));
+    }
+
+    public function testCurrencyObjectNullByDefault()
+    {
+        $this->assertNotNull($this->helper->getCurrency());
+    }
+
+    public function testLocalCurrencyObjectIsPreferredOverRegistry()
+    {
+        $currReg = new Zend_Currency('de_AT');
+        Zend_Registry::set('Zend_Currency', $currReg);
+
+        $this->helper = new Zend_View_Helper_Currency();
+        $this->assertSame($currReg, $this->helper->getCurrency());
+
+        $currLoc = new Zend_Currency('en_US');
+        $this->helper->setCurrency($currLoc);
+        $this->assertSame($currLoc, $this->helper->getCurrency());
+        $this->assertNotSame($currLoc, $currReg);
+    }
+
+    public function testHelperObjectReturnedWhenNoArgumentsPassed()
+    {
+        $helper = $this->helper->currency();
+        $this->assertSame($this->helper, $helper);
+
+        $currLoc = new Zend_Currency('de_AT');
+        $this->helper->setCurrency($currLoc);
+        $helper = $this->helper->currency();
+        $this->assertSame($this->helper, $helper);
+    }
+}
+
+// Call Zend_View_Helper_TranslateTest::main() if this source file is executed directly.
+if (PHPUnit_MAIN_METHOD == "Zend_View_Helper_TranslateTest::main") {
+    Zend_View_Helper_TranslateTest::main();
+}