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.
You must set the
FN(formatted name) andN(personal name) components; these are required by both 2.1 and 3.0 version vCards.
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.
Although the version 2.1 specification optionally allows parameter values to be indicated without without specified types (i.e, "
HOME" instead of "TYPE=HOME") the Contact_Vcard_Build class is not so lenient. With Contact_Vcard_Builder, you must set both the parameter kind and parameter value.
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();
?>
If you set values and parameters for components that are not part of the selected vCard version, they will not be included in the fetched vCard text.
You must have set the
FN(formatted name) andN(personal name) components, or the fetch() method will return a PEAR_Error object. TheFNandNcomponents are required by both 2.1 and 3.0 version vCards.