使用法
説明
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 を取得する方法
値とパラメータを追加したら、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 で必須となります。
忘却曲線を使ってこの知識を確実に記憶に残す
