Programmer's Reference Guide

Zend_Currency について

通貨の操作方法

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

例1 実際のロケールからの Zend_Currency のインスタンスの作成

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

$currency = new Zend_Currency();

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

// 起動ファイル内で
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);
 
// アプリケーションのどこかで
$currency = new Zend_Currency();

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

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

currency:

ひとつのロケールには複数の通貨を含めることができます。最初のパラメータ 'currency' では、どの通貨を使用するのかを定義します。定義する際には、その通貨の短い名前あるいは完全な名前を使用します。未知の通貨を指定した場合は例外をスローします。通貨の短い名前は、アルファベット大文字で 3 文字となります。たとえば USD (米ドル) や EUR (ユーロ) などがよく知られています。既知の通貨の一覧を得るメソッドが Zend_Currency に用意されています。
locale:

3 番目のパラメータ 'locale' は、通貨のフォーマットの際に使用するロケールを定義します。 script や currency が省略された場合は、このパラメータの内容をもとに標準の数字と通貨を取得します。

注意: Zend_Currency で使用できるロケールは、地域情報を含むものだけであることに注意しましょう。言語情報のみのロケールを指定すると、例外が発生します。たとえば en を指定するとエラーとなります。一方 en_US を指定すると、通貨は USD となります。

例2 Zend_Currency のインスタンスを作成する別の例

// 標準のロケールが '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');

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

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

通貨形式での出力の作成

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

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

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

例3 通貨形式での出力の作成

// '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.parsing.html#zend.locale.numbersystems にある 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 の作成時に設定した通貨記号を上書きします。

**通貨記号の設定を指定するための定数**
定数	説明
NO_SYMBOL	通貨を表す内容を表示しない
USE_SYMBOL	通貨記号を表示する
USE_SHORTNAME	3 文字で表される国際通貨略称を表示する
USE_NAME	通貨の完全な名称を表示する

**表示する場所を指定するための定数**
定数	説明
STANDARD	そのロケールにおける標準の位置に表示する
RIGHT	通貨表現を値の右側に表示する
LEFT	通貨表現を値の左側に表示する

例4 通貨の表示形式の変更

// '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_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 番目のパラメータには、どのロケールからデータを読み込むのかを指定します。これを省略した場合は、現在実際に設定されているロケールを使用します。

例5 通貨に関する情報の取得

// '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 に新しいロケールを設定します。この関数をコールすると、通貨のすべてのデフォルト値が上書きされます。つまり、通貨名や略称、記号などが上書きされるということです。

例6 新しいロケールの設定

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

Zend_Currency の高速化

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

例7 通貨のキャッシュ処理

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