repo_zf1/documentation/manual/ja/module_specs/Zend_Currency-Usage.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17597 -->
<sect1 id="zend.currency.usage">

    <title>通貨の操作方法</title>

    <para>
        <classname>Zend_Currency</classname> をアプリケーションで使用するには、
        何もパラメータを指定せずに単にそのインスタンスを作成します。
        これで、実際のロケールにもとづいた <classname>Zend_Currency</classname>
        のインスタンスができあがります。このインスタンスには、
        そのロケールで使用する通貨が定義されています。
    </para>

    <example id="zend.currency.usage.example1">

        <title>実際のロケールからの Zend_Currency のインスタンスの作成</title>

        <para>
            この例では、あなたの環境のロケールが 'en_US' であるものと仮定します。
            何もパラメータを指定せずに <classname>Zend_Currency</classname> のインスタンスを作成すると、
            実際の環境のロケールである 'en_US' を使用することになります。
            その結果として通貨単位は米ドルとなり、数値フォーマット規則は
            'en_US' となります。
        </para>

        <programlisting language="php"><![CDATA[
$currency = new Zend_Currency();
]]></programlisting>

    </example>

    <para>
        Zend Framework 1.7.0 以降、<classname>Zend_Currency</classname>
        アプリケーション単位でのロケールの指定をサポートするようになりました。
        下の例のように、<classname>Zend_Locale</classname> のインスタンスをレジストリに登録します。
        このようにすると、インスタンスを作成する際に
        いちいちロケールの設定を気にする必要がなくなります。
        これは同じロケールを何度も使用する場合に便利です。
    </para>

    <programlisting language="php"><![CDATA[
// 起動ファイル内で
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// アプリケーションのどこかで
$currency = new Zend_Currency();
]]></programlisting>

    <note>
        <para>
            システムでデフォルトのロケールが設定されていないかったり
            システムのロケールの検出に失敗したりした場合は、
            <classname>Zend_Currency</classname> は例外をスローします。
            このような場合は、ロケールを明示的に指定する必要があります。
        </para>
    </note>

    <para>
        もちろん、必要に応じてパラメータを指定してインスタンスを作成することもできます。
        各パラメータはオプションであり、省略可能です。
        またパラメータを指定する順番も変更することができます。
        パラメータの意味について、次にまとめます。
    </para>

    <itemizedlist mark='opencircle'>
        <listitem>
            <para>
                <emphasis>currency</emphasis>:
            </para>
            <para>
                ひとつのロケールには複数の通貨を含めることができます。
                最初のパラメータ <emphasis>'currency'</emphasis>
                では、どの通貨を使用するのかを定義します。
                定義する際には、その通貨の短い名前あるいは完全な名前を使用します。
                未知の通貨を指定した場合は例外をスローします。
                通貨の短い名前は、アルファベット大文字で 3 文字となります。
                たとえば <acronym>USD</acronym> (米ドル) や <acronym>EUR</acronym> (ユーロ)
                などがよく知られています。
                既知の通貨の一覧を得るメソッドが <classname>Zend_Currency</classname>
                に用意されています。
            </para>
        </listitem>
        <listitem>
            <para>
                <emphasis>locale</emphasis>:
            </para>
            <para>
                3 番目のパラメータ <emphasis>'locale'</emphasis>
                は、通貨のフォーマットの際に使用するロケールを定義します。
                script や currency が省略された場合は、
                このパラメータの内容をもとに標準の数字と通貨を取得します。
            </para>
            <note>
                <para>
                    <classname>Zend_Currency</classname> で使用できるロケールは、地域情報を含むものだけであることに注意しましょう。
                    言語情報のみのロケールを指定すると、例外が発生します。たとえば
                    <emphasis>en</emphasis> を指定するとエラーとなります。一方
                    <emphasis>en_US</emphasis> を指定すると、
                    通貨は <acronym>USD</acronym> となります。
                </para>
            </note>
        </listitem>
    </itemizedlist>

    <example id="zend.currency.usage.example2">

        <title>Zend_Currency のインスタンスを作成する別の例</title>

        <programlisting language="php"><![CDATA[
// 標準のロケールが 'de_AT' であるものとします

// 'en_US' でインスタンスを作成します。これは 'USD' を使用します ('en_US' のデフォルトの通貨です)
$currency = new Zend_Currency('en_US');

// 実際のロケール ('de_AT') で通貨として 'EUR' を使用するインスタンスを作成します
$currency = new Zend_Currency();

// 通貨として 'EUR'、数値フォーマットに 'en_US' を使用するインスタンスを作成します
$currency = new Zend_Currency('en_US', 'EUR');
]]></programlisting>

    </example>

    <para>
        デフォルトの値を使用する場合は、これらのパラメータはどれでも省略することができます。
        通貨を処理する際に、それによる悪影響は一切ありません。
        これは、たとえばその地域で実際に使われている通貨を知らない場合などに便利です。
    </para>

    <note>
        <para>
            複数の通貨を使用している国もあります。
            たとえば、現在流通しているもの以外に
            以前に使用していた通貨がある場合などです。
            '<emphasis>currency</emphasis>' パラメータを省略した場合は、
            現在流通している通貨を使用します。たとえば
            '<emphasis>de</emphasis>' (ドイツ) の通貨には
            '<acronym>EUR</acronym>' (ユーロ) と
            '<acronym>DEM</acronym>' (独マルク) がありますが、
            現在流通しているのは
            '<acronym>EUR</acronym>' です。
            パラメータを省略した場合はこちらを使用します。
        </para>
    </note>

    <sect2 id="zend.currency.usage.tocurrency">

        <title>通貨形式での出力の作成</title>

        <para>
            既存の値を通貨形式にフォーマットして出力するには
            <methodname>toCurrency()</methodname> メソッドを使用します。
            変換したい値をこのメソッドに渡します。
            この値には、正規化された数値ならなんでも指定できます。
        </para>

        <para>
            地域化された数字がある場合は、まずそれを
            <link linkend="zend.locale.number.normalize">Zend_Locale_Format::getNumber()</link>
            で正規化します。それから、その結果を
            <methodname>toCurrency()</methodname> に渡して通貨形式の出力を作成します。
        </para>

        <para>
            <methodname>toCurrency()</methodname> にはオプションで配列を指定することができます。
            この配列では、一時的なフォーマットや通貨表現を設定します。
            使用できるオプションについての詳細は
            <link linkend="zend.currency.usage.setformat">通貨の表示形式の変更</link>
            を参照ください。
        </para>

        <example id="zend.currency.usage.tocurrency.example">

            <title>通貨形式での出力の作成</title>

            <programlisting language="php"><![CDATA[
// 'en_US' でインスタンスを作成します。これは 'USD' を使用します ('en_US' のデフォルトの通貨です)
$currency = new Zend_Currency('en_US');

// '$ 1,000.00' と表示します
echo $currency->toCurrency(1000);

// '$ 1.000,00' と表示します
echo $currency->toCurrency(1000, array('format' => 'de_AT'));

// '$ ١٬٠٠٠٫٠٠' と表示します
echo $currency->toCurrency(1000, array('script' => 'Arab'));
]]></programlisting>

        </example>
    </sect2>

    <sect2 id="zend.currency.usage.setformat">

        <title>通貨の表示形式の変更</title>

        <para>
            <classname>Zend_Currency</classname> の作成時に指定したフォーマットが、
            当然標準の表示形式となります。しかし、ときにはそれを変更したくなることもあるでしょう。
        </para>

        <para>
            通貨の出力形式には、以下の要素があります。
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis>通貨記号、略称、あるいは名前</emphasis>:
                </para>
                <para>
                    通常は、通貨の出力時には通貨記号が表示されます。
                    必要に応じてこれを省略したり他の内容で置き換えたりすることができます。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>通貨記号の位置</emphasis>:
                </para>
                <para>
                    通貨記号の位置は、通常はロケールに応じて自動的に決まります。
                    必要に応じて、これを変更することができます。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>文字</emphasis>:
                </para>
                <para>
                    数値を表示する際に使用する文字です。詳細な情報は、
                    <classname>Zend_Locale</classname> のドキュメントにある
                    <link linkend="zend.locale.numbersystems">数値系の変換</link>
                    を参照ください。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>数値フォーマット</emphasis>:
                </para>
                <para>
                    通貨の量 (要するに、金額のことです) を表す際には、
                    そのロケールのフォーマット規則に合わせた表記になります。
                    たとえば、英語圏では 3 桁ごとの桁区切り文字に ',' を使用しますが、
                    ドイツでは '.' を使用します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            出力形式を変更したい場合は
            <methodname>setFormat()</methodname> メソッドを使用します。
            このメソッドに、変更したいすべてのオプションを含む配列を渡します。
            <varname>$options</varname> 配列がサポートしている設定は、次のとおりです。
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis>position</emphasis>:
                    通貨記号をどの位置に表示するのかを定義します。サポートしている位置は
                    <link linkend="zend.currency.usage.setformat.constantsposition">この表</link>
                    を参照ください。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>script</emphasis>:
                    数値の表示に使用する数字の種類を定義します。ほとんどのロケールでは、
                    デフォルトの数字は <emphasis>'Latn'</emphasis>
                    です。これは 0 から 9 を使用します。それ以外には
                    'Arab' (アラビア数字) なども使用できます。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>format</emphasis>:
                    数値を表示する際に使用するロケールを定義します。
                    数値フォーマットに含まれる内容としては、たとえば 3 桁ごとの区切り文字などがあります。
                    ロケール ID を指定してデフォルトのフォーマットを使用することもできますし、
                    数値フォーマットを手動で定義することもできます。
                    省略した場合は <classname>Zend_Currency</classname> オブジェクトのロケールを使用します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>display</emphasis>:
                    通貨を表す際に、通貨のどの部分を使用するのかを定義します。
                    使用できる表示形式は 4 通りです。
                    <link linkend="zend.currency.usage.setformat.constantsdescription">この表</link>
                    を参照ください。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>precision</emphasis>:
                    通貨を表現する際の精度を定義します。デフォルト値は
                    <emphasis>2</emphasis> です。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>name</emphasis>:
                    表示に使用する完全な通貨名を定義します。
                    このオプションは、<classname>Zend_Currency</classname>
                    の作成時に設定した通貨名を上書きします。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>currency</emphasis>:
                    表示に使用する国際通貨略称を定義します。
                    このオプションは、<classname>Zend_Currency</classname>
                    の作成時に設定した通貨略称を上書きします。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>symbol</emphasis>:
                    表示に使用する通貨記号を定義します。
                    このオプションは、<classname>Zend_Currency</classname>
                    の作成時に設定した通貨記号を上書きします。
                </para>
            </listitem>
        </itemizedlist>

        <table id="zend.currency.usage.setformat.constantsdescription">

            <title>通貨記号の設定を指定するための定数</title>

            <tgroup cols="2" align="left">
                <thead>
                    <row>
                        <entry>定数</entry>
                        <entry>説明</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><constant>NO_SYMBOL</constant></entry>
                        <entry>通貨を表す内容を表示しない</entry>
                    </row>
                    <row>
                        <entry><constant>USE_SYMBOL</constant></entry>
                        <entry>通貨記号を表示する</entry>
                    </row>
                    <row>
                        <entry><constant>USE_SHORTNAME</constant></entry>
                        <entry>3 文字で表される国際通貨略称を表示する</entry>
                    </row>
                    <row>
                        <entry><constant>USE_NAME</constant></entry>
                        <entry>通貨の完全な名称を表示する</entry>
                    </row>
                </tbody>
            </tgroup>

        </table>

        <table id="zend.currency.usage.setformat.constantsposition">

            <title>表示する場所を指定するための定数</title>

            <tgroup cols="2" align="left">
                <thead>
                    <row>
                        <entry>定数</entry>
                        <entry>説明</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><constant>STANDARD</constant></entry>
                        <entry>そのロケールにおける標準の位置に表示する</entry>
                    </row>
                    <row>
                        <entry><constant>RIGHT</constant></entry>
                        <entry>通貨表現を値の右側に表示する</entry>
                    </row>
                    <row>
                        <entry><constant>LEFT</constant></entry>
                        <entry>通貨表現を値の左側に表示する</entry>
                    </row>
                </tbody>
            </tgroup>

        </table>

        <example id="zend.currency.usage.setformat.example">

            <title>通貨の表示形式の変更</title>

            <programlisting language="php"><![CDATA[
// 'en_US' でインスタンスを作成します。これは 'USD'、'Latin' そして 'en_US' を使用します (これらは 'en_US' のデフォルトです)
$currency = new Zend_Currency('en_US');

// 'US$ 1,000.00' と表示します
echo $currency->toCurrency(1000);

$currency->setFormat(array('display' => Zend_Currency::USE_NAME,
                           'position' => Zend_Currency::RIGHT));

// '1.000,00 US Dollar' と表示します
echo $currency->toCurrency(1000);

$currency->setFormat(array('name' => 'American Dollar'));
// '1.000,00 American Dollar' と表示します
echo $currency->toCurrency(1000);

$currency->setFormat(array('format' => '##0.00'));
// '1000,00 American Dollar' と表示します
echo $currency->toCurrency(1000);
]]></programlisting>

        </example>
    </sect2>

    <sect2 id="zend.currency.usage.informational">

        <title>Zend_Currency の情報取得用メソッド</title>

        <para>
            もちろん、<classname>Zend_Currency</classname>
            では通貨に関する情報を <classname>Zend_Locale</classname>
            から取得するメソッドもサポートしています。これらを使用すると、
            現在用いられている通貨だけでなく以前に使われていたものについての情報も得ることができます。
            以下のようなメソッドが存在します。
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <emphasis><methodname>getSymbol()</methodname></emphasis>:
                </para>
                <para>
                    実際の通貨あるいは指定した通貨を表す通貨記号を返します。たとえば、
                    '<emphasis>en_US</emphasis>
                    ロケールにおける米ドルを表す記号は
                    <emphasis>$</emphasis> です。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><methodname>getShortName()</methodname></emphasis>:
                </para>
                <para>
                    実際の通貨あるいは指定した通貨の短い名前を返します。たとえば、
                    '<emphasis>en_US</emphasis>
                    ロケールにおける米ドルの短い名前は
                    <acronym>USD</acronym> です。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><methodname>getName()</methodname></emphasis>:
                </para>
                <para>
                    実際の通貨あるいは指定した通貨の完全な名前を返します。たとえば、
                    '<emphasis>en_US</emphasis>
                    ロケールにおける米ドルの完全な名前は
                    <emphasis>US Dollar</emphasis> です。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><methodname>getRegionList()</methodname></emphasis>:
                </para>
                <para>
                    実際の通貨あるいは指定した通貨が用いられている地域の一覧を返します。
                    ひとつの通貨が複数の地域で用いられている可能性もあるので、
                    返り値は常に配列となります。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><methodname>getCurrencyList()</methodname></emphasis>:
                </para>
                <para>
                    指定した地域で用いられている通貨の一覧を返します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            関数 <methodname>getSymbol()</methodname>、<methodname>getShortName()</methodname>
            および <methodname>getName()</methodname> には、それぞれオプションのパラメータを
            2 つ指定することができます。パラメータを省略した場合は、
            現在実際に設定されている通貨に対応するデータが返されます。
            最初のパラメータには短い形式の通貨名を指定します。
            これは常に 3 文字で、たとえばユーロなら <acronym>EUR</acronym>、
            米ドルなら <acronym>USD</acronym> となります。2 番目のパラメータには、
            どのロケールからデータを読み込むのかを指定します。
            これを省略した場合は、現在実際に設定されているロケールを使用します。
        </para>

        <example id="zend.currency.usage.informational.example">

            <title>通貨に関する情報の取得</title>

            <programlisting language="php"><![CDATA[
// 'en_US' でインスタンスを作成します。これは 'USD'、'Latin' そして 'en_US' を使用します (これらは 'en_US' のデフォルトです)
$currency = new Zend_Currency('en_US');

// '$' と表示します
echo $currency->getSymbol();

// 'EUR' と表示します
echo $currency->getShortName('EUR');

// 'Österreichische Schilling' と表示します
echo $currency->getName('ATS', 'de_AT');

// USD (米ドル) を使用しているすべての地域を配列で返します
print_r($currency->getRegionList();

// この地域で用いられているすべての通貨を配列で返します
print_r($currency->getCurrencyList('de_AT');
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.currency.usage.setlocale">

        <title>新しいデフォルト値の設定</title>

        <para>
            <methodname>setLocale()</methodname> メソッドは、
            <classname>Zend_Currency</classname> に新しいロケールを設定します。
            この関数をコールすると、通貨のすべてのデフォルト値が上書きされます。
            つまり、通貨名や略称、記号などが上書きされるということです。
        </para>

        <example id="zend.currency.usage.setlocale.example">

            <title>新しいロケールの設定</title>

            <programlisting language="php"><![CDATA[
// 米国の通貨を取得します
$currency = new Zend_Currency('en_US');
print $currency->toCurrency(1000);

// オーストリアの通貨を取得します
$currency->setLocale('de_AT');
print $currency->toCurrency(1000);
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.currency.usage.cache">

        <title>Zend_Currency の高速化</title>

        <para>
            <classname>Zend_Currency</classname> による作業を高速化するには
            <classname>Zend_Cache</classname> を使用します。これを使用するには、
            静的メソッド <methodname>Zend_Currency::setCache($cache)</methodname>
            に <classname>Zend_Cache</classname> アダプタを指定します。そうすると、
            <classname>Zend_Currency</classname> のメソッドで地域化したデータがキャッシュされるようになります。
            利便性を考慮して、静的メソッド
            <methodname>getCache()</methodname>、<methodname>hasCache()</methodname>、<methodname>clearCache()</methodname> および
            <methodname>removeCache()</methodname> も用意されています。
        </para>

        <example id="zend.currency.usage.cache.example">

            <title>通貨のキャッシュ処理</title>

            <programlisting language="php"><![CDATA[
// キャッシュオブジェクトを作成します
$cache = Zend_Cache::factory('Core',
                             'File',
                             array('lifetime' => 120,
                                   'automatic_serialization' => true),
                             array('cache_dir'
                                       => dirname(__FILE__) . '/_files/'));
Zend_Currency::setCache($cache);
]]></programlisting>
        </example>

    </sect2>

</sect1>