For the impatient. :-)
Contact_Vcard_Build.php in your PHP script.Example code:
<?php
// include the class file
require_once 'Contact_Vcard_Build.php';
// instantiate a builder object
// (defaults to version 3.0)
$vcard = new Contact_Vcard_Build();
// set a formatted name
$vcard->setFormattedName('Bolivar Shagnasty');
// set the structured name parts
$vcard->setName('Shagnasty', 'Bolivar', 'Odysseus',
'Mr.', 'III');
// add a work email. note that we add the value
// first and the param after -- Contact_Vcard_Build
// is smart enough to add the param in the correct
// place.
$vcard->addEmail('boshag@example.com');
$vcard->addParam('TYPE', 'WORK');
// add a home/preferred email
$vcard->addEmail('bolivar@example.net');
$vcard->addParam('TYPE', 'HOME');
$vcard->addParam('TYPE', 'PREF');
// add a work address
$vcard->addAddress('POB 101', 'Suite 202', '123 Main',
'Beverly Hills', 'CA', '90210', 'US');
$vcard->addParam('TYPE', 'WORK');
// get back the vCard and print it
$text = $vcard->fetch();
echo '<pre>';
print_r($text);
echo '</pre>';
?>
For a full overview of the vCard 3.0 specification, refer to Internet Engineering Task Force RFC 2426.
For a full overview of the vCard 2.1 specification (version 2.1), refer to the Internet Mail Consortium Product Developer Information web page.
Basically, a vCard is a plain text file that contains an "electronic business card" of contact information suitable for including in an address book. The vCard format is a standardized way of trading personal and organizational contact information.
These are some, but not all, of the components of a vCard:
Each line in a vCard is a separate component of the vCard. A component line consists of three things:
For example, consider the following component lines:
ADR;TYPE=WORK,PREF:;;123 Main;Beverly Hills;CA;90210;USEMAIL;TYPE=HOME;TYPE=INTERNET:nobody@example.comCATEGORIES:Personal,Business,FamilyPHOTO;TYPE=JPEG;VALUE=URI:http://example.com/photo.jpgComponent line 1 has an ADR type-definition (meaning a delivery address). It has a TYPE parameter of WORK and PREF, indicating that this a work address and is the preferred address for deliveries. Finally, the value of the component is a structured text value. Structured text value parts are delimited by semicolons; in the case of ADR components, the structured value parts are p.o. box, extended address, street address, city/locality, state/region, zip/postal code, and country.
Component line 2 has an EMAIL type-definition (meaning an email address). It has a TYPE parameter of HOME and INTERNET (meaning an internet email address for home). The component value is a single text value indicating the email address.
Component line 3 has a CATEGORIES type-definition (meaning the general categories of of this vCard). There are no parameters for this component. The component value is a repeating-text value. Repeated text values a delimited by commas.
Component line 4 has a PHOTO type-definition (meaning a personal photograph). The parameters indicate that the photo TYPE is JPEG (giving a hint to vCard decoders how to handle the PHOTO value) and that the component VALUE will be a URI (that is, a link to an external photo file). Finally, the component value is a single text value, revealing in this case the URI of the photo.
The 2.1 specification uses CRLF to terminate lines (\r\n). It allows the following components and parameters:
The 3.0 specification uses LF to terminate lines (\n). It allows the following components and parameters:
As shown in the quick instruction above, the basic use of Contact_Vcard_Build is straightforward: instantiate a builder object, add values and parameters, then fetch the resulting vCard.
To create an instance of a Contact_Vcard_Build ("builder") object, include the class file and issue a new directive:
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:
$vcard = new Contact_Vcard_Build('2.1');
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.
Note: you must set the FN (formatted name) and N (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...
// 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:
// 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.
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:
// 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:
// 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.
Note: 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.
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.
$text = $vcard->fetch();
Note 1: 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.
Note 2: you must have set the FN (formatted name) and N (personal name) components, or the fetch() method will return a PEAR_Error object. The FN and N components are required by both 2.1 and 3.0 version vCards.
There are no known bugs or outstanding issues at this time.
If you discover a new bug or want to contribute code to Contact_Vcard_Build, contact Paul M. Jones at pjones at ciaweb dot net; the subject line should start with [VCARD].
Contact_Vcard_Parse is a companion to Contact_Vcard_Build. Whereas Build makes new vCards, Parse reads existing vCards into an array. See the documentation page here.
Frank Hellwig has a 2.1/3.0 parser and address-book page generator. See his site at http://vcardphp.sourceforge.net/.
Kai Blankenhorn has a 2.1 card generator (not a parser). See his work at http://www.bitfolge.de/?s=phpvcard.
Flaimo has a vCard generator, too. http://flaimo.com/php_scripts.php (scroll down past the iCalendar stuff).
HORDE has a vCard data element in their application framework, but I don't quite see how to use it outside that framework. The doc pages for it are at http://dev.horde.org/api/horde/dev-doxygen/html/classData__vcard.html.
Of course, you can always Google for more vCard stuff under PHP, too: http://www.google.com/search?q=vcard+php.