Contact_Vcard_Build の基本的な使用法は簡単です。 ビルダオブジェクトのインスタンスを作成し、 値とパラメータを追加し、その結果の vCard を読み込みます。
Contact_Vcard_Build ("ビルダ") オブジェクトのインスタンスを作成するには、 クラスファイルをインクルードして new を実行します。
<?php
require_once 'Contact_Vcard_Build.php';
$vcard =& new Contact_Vcard_Build();
?>
デフォルトでは、バージョン 3.0 の vCard 用のビルダオブジェクトを作成します。
バージョン 2.1 の vCard を作成したい場合は、'2.1
'
をコンストラクタの引数で指定します。
<?php
$vcard =& new Contact_Vcard_Build('2.1');
?>
コンポーネントの値を設定する方法は二通りあります。 追加したいコンポーネントに特化したメソッドを使用する方法と、汎用的な setValue() および addValue() メソッドを使用する方法です。汎用的なメソッドは、 すべてのコンポーネント、繰り返し、構造化パートや値を扱うことができます。 一方、コンポーネント固有のメソッドは、簡単に使用できます。
FN
(formatted name) およびN
(personal name) コンポーネントを指定する必要があります。 これらは、2.1 および 3.0 の両方の vCard で必須となります。
たとえば、二つの ADR
コンポーネントを vCard に追加するには、ADR 固有のメソッドを使用して
<?php
// 最初の住所を指定します
$vcard->addAddress($pobox0, $extend0, $street0, $city0,
$state0, $zip0, $country0);
// 二番目の住所を指定します
$vcard->addAddress($pobox1, $extend1, $street1, $city1,
$state1, $zip1, $country1);
?>
とするか、汎用的なメソッドを使用して以下のようにします。
<?php
// 最初の住所 (iteration = 0) を指定します
$vcard->addValue('ADR', 0, VCARD_ADR_POB, $pobox0);
$vcard->addValue('ADR', 0, VCARD_ADR_EXTEND, $extend0);
$vcard->addValue('ADR', 0, VCARD_ADR_STREET, $street0);
$vcard->addValue('ADR', 0, VCARD_ADR_LOCALITY, $city0);
$vcard->addValue('ADR', 0, VCARD_ADR_REGION, $state0);
$vcard->addValue('ADR', 0, VCARD_ADR_POSTCODE, $zip0);
$vcard->addValue('ADR', 0, VCARD_ADR_COUNTRY, $country0);
// 二番目の住所 (iteration = 1) を指定します
$vcard->addValue('ADR', 1, VCARD_ADR_POB, $pobox1);
$vcard->addValue('ADR', 1, VCARD_ADR_EXTEND, $extend1);
$vcard->addValue('ADR', 1, VCARD_ADR_STREET, $street1);
$vcard->addValue('ADR', 1, VCARD_ADR_LOCALITY, $city1);
$vcard->addValue('ADR', 1, VCARD_ADR_REGION, $state1);
$vcard->addValue('ADR', 1, VCARD_ADR_POSTCODE, $zip1);
$vcard->addValue('ADR', 1, VCARD_ADR_COUNTRY, $country1);
?>
Contact_Vcard_Build.php
のインラインコメントで、
コンポーネント固有の各メソッドの使用法をご確認ください。
パラメータを追加する方法はひとつだけです。 addParam() メソッドを使用します。 値を追加する場合と異なり、コンポーネント固有のメソッドはありません。
一般に、コンポーネントのパラメータを追加するのは、 コンポーネントの値を設定し終えた直後です。 なぜなら、最後に値が追加されたコンポーネントが何であるかをビルダオブジェクトが知っているからです (コンポーネント固有のパラメータ追加メソッドがない理由はこれです)。
たとえば、上のコードの ADR
コンポーネントにパラメータを設定するには、次のようにします。
<?php
// 最初の住所を追加します
$vcard->addAddress($pobox0, $extend0, $street0, $city0,
$state0, $zip0, $country0);
// 最初の住所のパラメータを追加します
$vcard->addParam('TYPE', 'HOME');
$vcard->addParam('TYPE', 'PREF');
// 二番目の住所を追加します
$vcard->addAddress($pobox1, $extend1, $street1, $city1,
$state1, $zip1, $country1);
// 二番目の住所のパラメータを追加します
$vcard->addParam('TYPE', 'WORK');
?>
このようにして、最初の住所には TYPE=HOME,PREF
そして二番目の住所には TYPE=WORK
というパラメータを指定します。
別の方法として、同じ addParam() メソッドに追加の引数を指定することで、 パラメータを直接追加することもできます。
<?php
// 最初の住所
// (component = ADR, iteration = 0) にパラメータを追加します
$vcard->addParam('TYPE', 'HOME', 'ADR', 0);
$vcard->addParam('TYPE', 'PREF', 'ADR', 0);
// 二番目の住所
// (component = ADR, iteration = 1) にパラメータを追加します
$vcard->addParam('TYPE', 'WORK', 'ADR', 1);
?>
これは、先ほどの addParam() のコードと同じことを行います。
バージョン 2.1 の仕様では、パラメータの種類を指定せずに値だけを指定する (つまり "
TYPE=HOME
" ではなく "HOME
" とする) ことも許可しています。しかし Contact_Vcard_Build クラスはそれほど寛容ではありません。 Contact_Vcard_Builder を使用する場合は、 パラメータの種類と値の両方を指定する必要があります。
値とパラメータを追加したら、vCard に戻って fetch()
メソッドを使用します。これはそのコンポーネント、パラメータそして値
(BEGIN:VCARD
および END:VCARD
を含む)
を、vCard のバージョンにあわせた適切な書式で返します。
<?php
$text = $vcard->fetch();
?>
選択した vCard のバージョンにないコンポーネントの値やパラメータを指定した場合は、 それは取得した vCard テキストには含まれません。
FN
(formatted name) およびN
(personal name) コンポーネントは必ず設定しなければなりません。 そうしないと fetch() メソッドは PEAR_Error オブジェクトを返します。FN
およびN
コンポーネントは、 バージョン 2.1 および 3.0 の両方の vCard で必須となります。