repo_zf1Php7/documentation/manual/en/module_specs/Zend_Currency-Description.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.currency.description">
    <title>What makes a currency?</title>

    <para>
        The currency consists of several informations. A name, a abbreviation and a sign. Each
        of these could be relevant to be displayed, but only one at the same time. It would not
        be a good practice to display something like "USD 1.000 $".
    </para>

    <para>
        Therefor <classname>Zend_Currency</classname> supports the definition of the currency
        information which has to be rendered. The following constants can be used:
    </para>

    <table id="zend.currency.description.table-1">
        <title>Rendered informations for a currency</title>

        <tgroup cols="2" align="left">
            <thead>
                <row>
                    <entry>Constant</entry>
                    <entry>Description</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry><constant>NO_SYMBOL</constant></entry>
                    <entry>No currency representation will be rendered at all</entry>
                </row>

                <row>
                    <entry><constant>USE_SYMBOL</constant></entry>

                    <entry>
                        The currency symbol will be rendered. For US Dollar this would be '$'
                    </entry>
                </row>

                <row>
                    <entry><constant>USE_SHORTNAME</constant></entry>

                    <entry>
                        The abbreviation for this currency will be rendered. For US Dollar this
                        would be 'USD'. Most abbreviations consist of 3 characters
                    </entry>
                </row>

                <row>
                    <entry><constant>USE_NAME</constant></entry>

                    <entry>
                        The full name for this currency will be rendered. For US Dollar the full
                        name would be "US Dollar"
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <example id="zend.currency.description.example-1">
        <title>Selecting the currency description</title>

        <para>
            Let's assume that your client has again set "en_US" as locale. Using no option the
            returned value could look like this:
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency(
    array(
        'value' => 100,
    )
);

print $currency; // Could return '$ 100'
]]></programlisting>

        <para>
            By giving the proper option you can define what information which has to be
            rendered.
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency(
    array(
        'value'   => 100,
        'display' => Zend_Currency::USE_SHORTNAME,
    )
);

print $currency; // Could return 'USD 100'
]]></programlisting>

        <para>
             Without providing the <property>display</property> the currency sign will be used
            when rendering the object. When the currency has no sign, the abbreviation will be
            used as replacement.
        </para>
    </example>

    <note>
        <title>Not all currencies have signs</title>

        <para>
            You should note that not all currencies have default currency signs. This means,
            that when there is no default sign, and you set the sign to be rendered, you will
            not have a rendered currency at all because the sign is an empty string.
        </para>
    </note>

    <para>
        Sometimes it is necessary to change the default informations. You can set each of the
        three currency informations independently by giving the proper option. See the following
        example.
    </para>

    <example id="zend.currency.description.example-2">
        <title>Changing the currency description</title>

        <para>
            Let's assume that your client has again set "en_US" as locale. But now we don't want
            to use the default settings but set our own description. This can simply be done
            providing the proper option:
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency(
    array(
        'value' => 100,
        'name'  => 'Dollar',
    )
);

print $currency; // Could return 'Dollar 100'
]]></programlisting>

        <para>
            You could also set a sign or an abbreviations yourself.
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency(
    array(
        'value'    => 100,
        'symbol' => '$$$',
    )
);

print $currency; // Could return '$$$ 100'
]]></programlisting>
    </example>

    <note>
        <title>Automatic display settings</title>

        <para>
            When you set a name, abbreviation or sign yourself, than this new information will
            automatically be set to be rendered. This simplification prevents you from setting
            the proper <property>display</property> option when you set a information.
        </para>

        <para>
            So using the <property>sign</property> option you can omit
            <property>display</property> and don't neet to setting it to
            '<constant>USE_SYMBOL</constant>'.
        </para>
    </note>
</sect1>