Usage

Description

The basic use of Contact_Vcard_Build is straightforward: instantiate a builder object, add values and parameters, then fetch the resulting vCard.

Instantiation

To create an instance of a Contact_Vcard_Build ("builder") object, include the class file and issue a new directive:

<?php
    require_once 'Contact_Vcard_Build.php';
    $vcard =& new Contact_Vcard_Build();
?>

By default, this creates a builder object that will allow you to fetch a version 3.0 vCard. If you want to build a version 2.1 vCard, pass '2.1' as the only constructor argument:

<?php
    $vcard =& new Contact_Vcard_Build('2.1');
?>

How To Set A Component Value

There are two ways to set the value of a component: use the method specifically for the component you want to add, or use the generic setValue() and addValue() methods. While the generic methods allow you direct control over every individual component, iteration, structured part, and value repetition, the component-specific methods are often easier to use.

For example, if you want to add two ADR components to the vCard, you can do it with the ADR-specific method...

<?php
    // add first address iteration
    $vcard->addAddress($pobox0, $extend0, $street0, $city0, 
        $state0, $zip0, $country0);

    // add second address iteration
    $vcard->addAddress($pobox1, $extend1, $street1, $city1, 
        $state1, $zip1, $country1);
?>

...or you can use the generic methods:

<?php
    // add first address (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);

    // add second address (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);
?>

Please see the Contact_Vcard_Build.php inline comments for descriptions of how to use each component-specific method.

How To Set A Parameter Value

There is only one way to add a parameter: use the addParam() method. Unlike with adding values, there are no component-specifc methods to add parameters.

In general, you should add the parameters of a component immediately after you add the complete value of a component, because the builder object keeps track of what was the last component value added. (This is why there are no component-specific add-parameter methods.)

For example, we can set the params for the ADR components as in the above code:

<?php
    // add first address iteration
    $vcard->addAddress($pobox0, $extend0, $street0, $city0, 
        $state0, $zip0, $country0);

    // add parameters to the first address
    $vcard->addParam('TYPE', 'HOME');
    $vcard->addParam('TYPE', 'PREF');

    // add second address iteration
    $vcard->addAddress($pobox1, $extend1, $street1, $city1, 
        $state1, $zip1, $country1);

    // add parameters to the second address
    $vcard->addParam('TYPE', 'WORK');
?>

Thus, the first address will have TYPE=HOME,PREF and the second will have TYPE=WORK as their parameters.

Alternatively, you can add parameters directly using the same addParam() method, with some additional arguments:

<?php
    // add parameters to the first address iteration
    // (component = ADR, iteration = 0)
    $vcard->addParam('TYPE', 'HOME', 'ADR', 0);
    $vcard->addParam('TYPE', 'PREF', 'ADR', 0);

    // add parameters to the second address iteration
    // (component = ADR, iteration = 1)
    $vcard->addParam('TYPE', 'WORK', 'ADR', 1);
?>

This does the same thing as the earlier addParam() code.

How To Fetch A vCard

After you have added all the values and parameters that you want, you get back the vCard using the fetch() method. This will return the components, parameters, and values (including BEGIN:VCARD and END:VCARD) in proper format for the vCard version.

<?php
    $text = $vcard->fetch();
?>