使用法

使用法 – Contact_VCard_Build の使用法

説明

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'0VCARD_ADR_POB,      $pobox0);
    
$vcard->addValue('ADR'0VCARD_ADR_EXTEND,   $extend0);
    
$vcard->addValue('ADR'0VCARD_ADR_STREET,   $street0);
    
$vcard->addValue('ADR'0VCARD_ADR_LOCALITY$city0);
    
$vcard->addValue('ADR'0VCARD_ADR_REGION,   $state0);
    
$vcard->addValue('ADR'0VCARD_ADR_POSTCODE$zip0);
    
$vcard->addValue('ADR'0VCARD_ADR_COUNTRY,  $country0);

    
// 二番目の住所 (iteration = 1) を指定します
    
$vcard->addValue('ADR'1VCARD_ADR_POB,      $pobox1);
    
$vcard->addValue('ADR'1VCARD_ADR_EXTEND,   $extend1);
    
$vcard->addValue('ADR'1VCARD_ADR_STREET,   $street1);
    
$vcard->addValue('ADR'1VCARD_ADR_LOCALITY$city1);
    
$vcard->addValue('ADR'1VCARD_ADR_REGION,   $state1);
    
$vcard->addValue('ADR'1VCARD_ADR_POSTCODE$zip1);
    
$vcard->addValue('ADR'1VCARD_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 で必須となります。

vCard 2.1 および 3.0 のテキストブロックを作成して読み込む (Previous) Contact_Vcard_Parse (Next)
Last updated: Sat, 19 Apr 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.