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

地域化された数字がある場合は、まずそれを Zend_Locale_Format::getNumber() で正規化します。それから、その結果を toCurrency() に渡して通貨形式の出力を作成します。

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

// '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'));

            

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

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

• 通貨記号、略称、あるいは名前:

  通常は、通貨の出力時には通貨記号が表示されます。 必要に応じてこれを省略したり他の内容で置き換えたりすることができます。

• 通貨記号の位置:

  通貨記号の位置は、通常はロケールに応じて自動的に決まります。 必要に応じて、これを変更することができます。

• 文字:

  数値を表示する際に使用する文字です。詳細な情報は、 Zend_Locale のドキュメントにある サポートする数値系 を参照ください。

• 数値フォーマット:

  通貨の量 (要するに、金額のことです) を表す際には、 そのロケールのフォーマット規則に合わせた表記になります。 たとえば、英語圏では 3 桁ごとの桁区切り文字に ',' を使用しますが、 ドイツでは '.' を使用します。

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

• position: 通貨記号をどの位置に表示するのかを定義します。サポートしている位置は この表 を参照ください。

• script: 数値の表示に使用する数字の種類を定義します。ほとんどのロケールでは、 デフォルトの数字は 'Latn' です。これは 0 から 9 を使用します。それ以外には 'Arab' (アラビア数字) なども使用できます。サポートしている数字は この表 を参照ください。

• format: 数値を表示する際に使用するロケールを定義します。 数値フォーマットに含まれる内容としては、たとえば 3 桁ごとの区切り文字などがあります。 ロケール ID を指定してデフォルトのフォーマットを使用することもできますし、 数値フォーマットを手動で定義することもできます。 省略した場合は Zend_Currency オブジェクトのロケールを使用します。

• display: 通貨を表す際に、通貨のどの部分を使用するのかを定義します。 使用できる表示形式は 4 通りです。 この表 を参照ください。

• precision: 通貨を表現する際の精度を定義します。デフォルト値は 2 です。

• name: 表示に使用する完全な通貨名を定義します。 このオプションは、Zend_Currency の作成時に設定した通貨名を上書きします。

• currency: 表示に使用する国際通貨略称を定義します。 このオプションは、Zend_Currency の作成時に設定した通貨略称を上書きします。

• symbol: 表示に使用する通貨記号を定義します。 このオプションは、Zend_Currency の作成時に設定した通貨記号を上書きします。

// '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);

            

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

• getSymbol():

  実際の通貨あるいは指定した通貨を表す通貨記号を返します。たとえば、 'en_US ロケールにおける米ドルを表す記号は $ です。

• getShortName():

  実際の通貨あるいは指定した通貨の短い名前を返します。たとえば、 'en_US ロケールにおける米ドルの短い名前は USD です。

• getName():

  実際の通貨あるいは指定した通貨の完全な名前を返します。たとえば、 'en_US ロケールにおける米ドルの完全な名前は US Dollar です。

• getRegionList():

  実際の通貨あるいは指定した通貨が用いられている地域の一覧を返します。 ひとつの通貨が複数の地域で用いられている可能性もあるので、 返り値は常に配列となります。

• getCurrencyList():

  指定した地域で用いられている通貨の一覧を返します。

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

// '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');

            

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

// 米国の通貨を取得します
$currency = new Zend_Currency('en_US');
print $currency->toCurrency(1000);

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

            

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

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