Home » File Formats » Contact_Vcard_Build » Manual

Introduction

Introduction – Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Contact_Vcard_Build Description

Allows you to programmatically create a vCard, version 2.1 or 3.0, and fetch the vCard text.

Quick Instructions

• Download and un-compress Contact_Vcard_Build from the PEAR archive.
• Include Contact_Vcard_Build.php in your PHP script.
• Instantiate a new Contact_Vcard_Build object (by default, the vCard version is 3.0, but 2.1 vCards are also supported).
• Set or add values and parameters that you want in the vCard.
• Fetch the completed vCard, then use print_r() to view the results.

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>';
?>

Differences Between vCard 2.1 and vCard 3.0

The 2.1 specification uses CRLF to terminate lines (\r\n). It allows the following components and parameters:

• Parameters:
  • TYPE of DOM, INTL, POSTAL, PARCEL, HOME, WORK, PREF, VOICE, FAX, MSG, CELL, PAGER, BBS, MODEM, CAR, ISDN, VIDEO, AOL, APPLELINK, ATTMAIL, CIS, EWORLD, INTERNET, IBMMAIL, MCIMAIL, POWERSHARE, PRODIGY, TLX, X400, GIF, CGM, WMF, BMP, MET, PMB, DIB, PICT, TIFF, PDF, PS, JPEG, QTIME, MPEG, MPEG2, AVI, WAVE, AIFF, PCM, X509, or PGP.
  • ENCODING of 7BIT, 8BIT, BASE64, QUOTED-PRINTABLE
  • VALUE of INLINE, CONTENT-ID, CID, URL, VCARD
  • CHARSET of any ISO charset specification.
  • LANGUAGE is very lenient, basically anything so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).
• Components and methods
  • VERSION (setVersion())
  • FN (setFormattedName())
  • N (setName())
  • PHOTO (setPhoto())
  • BDAY (setBirthday())
  • ADR (addAddress())
  • LABEL (addLabel())
  • TEL (addTelephone())
  • EMAIL (addEmail())
  • MAILER (setMailer())
  • TZ (setTZ())
  • GEO (setGeo())
  • TITLE (setTitle())
  • ROLE (setRole())
  • LOGO (setLogo())
  • AGENT (setAgent())
  • ORG (addOrganization())
  • NOTE (setNote())
  • REV (setRevision())
  • SOUND (setSound())
  • URL (setURL())
  • KEY (setKey())

The 3.0 specification uses LF to terminate lines (\n). It allows the following components and parameters:

• Parameters:
  • TYPE of any of the 2.1 TYPE values, or any other value so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).
  • ENCODING of 8BIT and B ("binary").
  • VALUE of BINARY, PHONE-NUMBER, TEXT, URI, UTC-OFFSET, or VCARD.
• Components and Methods:
  • VERSION (setVersion())
  • FN (setFormattedName())
  • N (setName())
  • NAME (setSourceName())
  • SOURCE (setSource())
  • NICKNAME (addNickname())
  • PHOTO (setPhoto())
  • BDAY (setBirthday())
  • ADR (addAddress())
  • LABEL (addLabel())
  • TEL (addTelephone())
  • EMAIL (addEmail())
  • MAILER (setMailer())
  • TZ (setTZ())
  • GEO (setGeo())
  • TITLE (setTitle())
  • ROLE (setRole())
  • LOGO (setLogo())
  • AGENT (setAgent())
  • ORG (addOrganization())
  • CATEGORIES (addCategories())
  • NOTE (setNote())
  • PRODID (setProductID())
  • REV (setRevision())
  • SORT-STRING (setSortString())
  • SOUND (setSound())
  • UID (setUniqueID())
  • URL (setURL())
  • CLASS (setClass())
  • KEY (setKey())

Usage

Usage – How to use Contact_VCard_Build

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) 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...

<?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) 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.